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:

{
  "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 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 quickstart.
`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 for longer than expected, check the status and paused_reason fields:

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.

Duplicate messages being delivered

The Trigger Inbox API uses at-least-once delivery. 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 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:

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.

Use cases

Implementation

Trigger Inbox

Trigger Inbox errors

Trigger Inbox errors

Error response format

HTTP error codes

Inbox stays in `initializing`

Inbox moves to `paused` unexpectedly

Duplicate messages being delivered

Message quarantined

​Trigger Inbox errors

​Error response format

​HTTP error codes

​Inbox stays in initializing

​Inbox moves to paused unexpectedly

​Duplicate messages being delivered

​Message quarantined

​Related resources

Trigger Inbox errors

Error response format

HTTP error codes

Inbox stays in `initializing`

Inbox moves to `paused` unexpectedly

Duplicate messages being delivered

Message quarantined

Related resources