Skip to main content

​
Error handling

This page covers errors during the connection flow and token exchange. For MCP server errors (tool execution failures, protocol errors), see the MCP specification on error handling. When an error occurs during the connection flow, Zapier redirects the user back to your redirect_uri with an error code and optionally a description.

​
Error response format

https://your-domain.com/callback?error={error_code}&error_description={description}&state={state}
ParameterTypeDescription
errorstringOne of the error codes below
error_descriptionstringOptional human-readable detail
statestringEchoed from your original request (if provided)

​
Error codes

CodeMeaning
invalid_requestThe request is malformed or missing required data. Check your parameters and retry.
access_deniedThe user or session does not have permission. Re-initiate the connection flow.
server_errorAn unexpected internal error occurred. Retry, or contact Zapier support if persistent.

​
Redirect errors

These errors are returned as redirects to your redirect_uri with the error parameters above.
Error codeDescriptionCauseAction
invalid_requestInvalid tokenThe connect token is invalid or malformed.Generate a new connect token and retry.
invalid_requestToken expiredThe connect token expired before Zapier could start a session.Generate a new connect token and retry.
invalid_requestInvalid appThe app name is not recognized.Verify the app id against the apps API.
access_deniedUser not foundThe provisioned user or account could not be found.Re-initiate the connection flow.
server_errorSession initialization failedThe connect token could not be validated (unknown upstream error).Generate a new connect token and retry.
server_errorAn unexpected error occurredAn internal error occurred while fetching app info, creating the connection, or setting up the MCP server.Retry, or contact Zapier support if persistent.
server_errorOAuth Failed: {detail}The third-party app OAuth flow failed (user denied consent, token exchange error, or permission error).Prompt the user to try connecting again.
server_errorOAuth FailedThe third-party app OAuth flow failed with an unknown error.Prompt the user to try connecting again.

​
Non-redirect errors

These errors are returned as HTTP responses before redirect_uri has been validated.

​
Token exchange (POST /oauth/token)

Token exchange errors return JSON responses since this is a backend-to-backend call.
HTTP statusErrorDescriptionAction
400invalid_grantJWT validation failed (expired, bad signature, missing claims)Check JWT claims, signing key, and expiry.
401invalid_clientUnknown client_id or wrong client_secretVerify your credentials.
400invalid_requestMissing required parametersCheck request parameters against Token exchange.
Example error response: 
{
  "error": "invalid_grant",
  "error_description": "JWT validation failed: token has expired"
}

​
Token refresh (POST /oauth/token)

Refresh token errors also return JSON responses.
HTTP statusErrorDescriptionAction
400invalid_grantRefresh token is expired, revoked, or invalidRe-initiate the full connection flow to obtain new tokens.
401invalid_clientUnknown client_id or wrong client_secretVerify your credentials.
See Token exchange — refreshing for the request format.

​
Connection flow

Connection flow errors are returned in one of two ways:
  • If a valid redirect_uri is present: Zapier redirects to it with ?error={error_code}&error_description={description} query parameters (see Redirect errors above).
  • Otherwise: Zapier returns an HTML error page directly to the user.
HTTP statusCauseAction
400Invalid or expired token parameterGenerate a new connect token and retry.
400Missing redirect_uriEnsure redirect_uri is included in the request.
400Missing client_id or redirect_uri in sessionRe-initiate the connection flow.
404Missing token parameterEnsure the connect token is passed as token.