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

# Trigger Inbox errors

> Error codes and unexpected behavior with the Trigger Inbox API.

# Trigger Inbox errors

## Error response format

All API errors return a JSON body with an `errors` array. Each error object contains:

| Field    | Type    | Required | Description                                            |
| -------- | ------- | -------- | ------------------------------------------------------ |
| `code`   | string  | Yes      | Machine-readable error identifier                      |
| `detail` | string  | Yes      | Human-readable explanation of this specific occurrence |
| `status` | integer | No       | HTTP status code repeated in the body                  |
| `title`  | string  | No       | Short summary of the problem type                      |
| `source` | object  | No       | Reference to the field or value that caused the error  |

Example:

```json theme={null}
{
  "errors": [
    {
      "code": "unauthenticated",
      "detail": "Token has expired.",
      "status": 400,
      "title": "Authentication error"
    }
  ]
}
```

Use `errors[0].code` to identify the error type programmatically. Use `errors[0].detail` for the human-readable explanation of the specific failure.

***

## HTTP error codes

| Status | Code               | Cause                                                                                  | Action                                                                                                                                                                                                                                                                                                                                    |
| ------ | ------------------ | -------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `unauthenticated`  | Bearer token has expired or is no longer valid.                                        | Generate a new access token. Go to [Token exchange](/white-label/implementation/token-exchange) for the token exchange request.                                                                                                                                                                                                           |
| `400`  | varies             | A required field is missing or a field value is invalid.                               | Check `errors[0].detail`. It identifies which field failed validation and why. Verify your request body matches the expected schema.                                                                                                                                                                                                      |
| `401`  | `invalid_audience` | Token was not issued via `POST https://zapier.com/oauth/token`.                        | Re-generate the token using the correct endpoint and scope (`external`).                                                                                                                                                                                                                                                                  |
| `401`  | —                  | The `Authorization` header is missing the `Bearer` prefix.                             | The header must be `Authorization: Bearer YOUR_TOKEN`, not just `Authorization: YOUR_TOKEN`.                                                                                                                                                                                                                                              |
| `404`  | —                  | The inbox ID is missing, incorrect, or belongs to a deleted inbox.                     | Verify your `$INBOX_ID` variable is set: `echo $INBOX_ID` should return a UUID. Retry with the correct ID.                                                                                                                                                                                                                                |
| `409`  | —                  | An inbox with that name already exists but has a different subscription configuration. | Use a different name if the conflict is unintentional. Delete the existing inbox and recreate it with the new configuration. Investigate if the conflict is unexpected. It may indicate a deployment misconfiguration. For more, go to [Trigger Inbox onboarding](/white-label/trigger-inbox/trigger-inbox-onboarding).                   |
| `429`  | —                  | You have exceeded the rate limit.                                                      | Check the `Retry-After` response header. It specifies how many seconds to wait before retrying. Implement exponential backoff in your polling loop: start with a 5-second delay and double it on each empty response, up to a maximum of 60 seconds. Also check `X-RateLimit-Remaining` and `X-RateLimit-Reset` for current window state. |

***

## Inbox stays in `initializing`

If the inbox remains in [`initializing`](/white-label/trigger-inbox/what-is-trigger-inbox-api#inbox-states) for longer than expected, check the `status` and `paused_reason` fields:

```bash theme={null}
curl -s "https://api.zapier.com/trigger-inbox/v1/inboxes/$INBOX_ID" \
  -H "Authorization: Bearer $TOKEN" \
  | python3 -c "import sys,json; d=json.load(sys.stdin); print(d['status'], d.get('paused_reason'))"
```

If `status` is `initialization_failure`, the subscription setup failed. You cannot resume from this state. Delete the inbox and create a new one.

***

## Inbox moves to `paused` unexpectedly

Common causes include expired app account credentials (`authentication`) or a problem with the connected app (`upstream_failures`).

Check the `paused_reason` field and follow the guidance in [Manage your inbox](/white-label/trigger-inbox/manage-your-inbox#handle-an-inbox-paused-by-zapier).

***

## Duplicate messages being delivered

The Trigger Inbox API uses [at-least-once delivery](/white-label/trigger-inbox/what-is-trigger-inbox-api#how-it-works). If a lease expires before acknowledgment, the message returns to the queue and may be leased again. Build idempotent processing and check the message `id` before acting on a payload.

***

## Message quarantined

A [quarantined](/white-label/trigger-inbox/what-is-trigger-inbox-api#message-lifecycle) message is no longer returned by lease calls but remains visible in list calls for inspection.

Inspect the quarantined message to determine whether it should be reprocessed or dropped:

```bash theme={null}
curl -s "https://api.zapier.com/trigger-inbox/v1/inboxes/$INBOX_ID/messages" \
  -H "Authorization: Bearer $TOKEN" | python3 -m json.tool
```

To drop a bad message before it reaches the quarantine threshold, acknowledge it explicitly using the lease ID. This permanently removes it without processing.

***

## Related resources

* [Manage your inbox](/white-label/trigger-inbox/manage-your-inbox)
* [Trigger Inbox onboarding](/white-label/trigger-inbox/trigger-inbox-onboarding)
* [Trigger Inbox API reference](/white-label/api-reference/inboxes/list-inboxes)