> ## 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`.    |