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}

Parameter	Type	Description
`error`	string	One of the error codes below
`error_description`	string	Optional human-readable detail
`state`	string	Echoed from your original request (if provided)

Error codes

Code	Meaning
`invalid_request`	The request is malformed or missing required data. Check your parameters and retry.
`access_denied`	The user or session does not have permission. Re-initiate the connection flow.
`server_error`	An 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 code	Description	Cause	Action
`invalid_request`	`Invalid token`	The connect token is invalid or malformed.	Generate a new connect token and retry.
`invalid_request`	`Token expired`	The connect token expired before Zapier could start a session.	Generate a new connect token and retry.
`invalid_request`	`Resource does not match connect token`	The `resource` parameter does not match the resource the connect token was issued for.	Ensure the resource URL matches what was used during token exchange.
`invalid_request`	`redirect_uri is not allowed`	The `redirect_uri` is not registered for this client.	Verify your `redirect_uri` is registered with Zapier.
`invalid_request`	`Invalid app`	The app name is not recognized.	Verify the app id against the apps API.
`access_denied`	`User not found`	The provisioned user or account could not be found.	Re-initiate the connection flow.
`server_error`	`Session initialization failed`	The connect token could not be validated (unknown upstream error).	Generate a new connect token and retry.
`server_error`	`An unexpected error occurred`	An internal error occurred while fetching app info, creating the connection, or setting up the MCP server.	Retry, or contact Zapier support if persistent.
`server_error`	`OAuth 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_error`	`OAuth Failed`	The 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 status	Error	Description	Action
400	`invalid_grant`	JWT validation failed (expired, bad signature, missing claims)	Check JWT claims, signing key, and expiry.
401	`invalid_client`	Unknown `client_id` or wrong `client_secret`	Verify your credentials.
400	`invalid_request`	Missing required parameters	Check 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 status	Error	Description	Action
400	`invalid_grant`	Refresh token is expired, revoked, or invalid	Re-initiate the full connection flow to obtain new tokens.
401	`invalid_client`	Unknown `client_id` or wrong `client_secret`	Verify 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 status	Cause	Action
400	Invalid or expired `token` parameter	Generate a new connect token and retry.
400	Missing `redirect_uri`	Ensure `redirect_uri` is included in the request.
400	Missing `client_id` or `redirect_uri` in session	Re-initiate the connection flow.
404	Missing `token` parameter	Ensure the connect token is passed as `token`.

Use cases

Implementation

Trigger Inbox

Error handling

Error handling

Error response format

Error codes

Redirect errors

Non-redirect errors

Token exchange (`POST /oauth/token`)

Token refresh (`POST /oauth/token`)

Connection flow

​Error handling

​Error response format

​Error codes

​Redirect errors

​Non-redirect errors

​Token exchange (POST /oauth/token)

​Token refresh (POST /oauth/token)

​Connection flow

Error handling

Error response format

Error codes

Redirect errors

Non-redirect errors

Token exchange (`POST /oauth/token`)

Token refresh (`POST /oauth/token`)

Connection flow