> ## Documentation Index
> Fetch the complete documentation index at: https://docs.zapier.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Error handling

> Error codes and responses for the connection flow, token exchange, and token refresh.

# 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](https://modelcontextprotocol.io/specification/2025-06-18/server/tools#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

```text theme={null}
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](./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](/powered-by-zapier/api-reference/experimental/get-whitelabel-apps). |
| `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](./token-exchange). |

Example error response:

```json theme={null}
{
  "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](./token-exchange) 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](#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`. |