Skip to main content

​
Trigger Inbox errors

​
Error response format

All API errors return a JSON body with an errors array. Each error object contains:
FieldTypeRequiredDescription
codestringYesMachine-readable error identifier
detailstringYesHuman-readable explanation of this specific occurrence
statusintegerNoHTTP status code repeated in the body
titlestringNoShort summary of the problem type
sourceobjectNoReference 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

StatusCodeCauseAction
400unauthenticatedBearer token has expired or is no longer valid.Generate a new access token. Go to Token exchange for the token exchange request.
400variesA 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.
401invalid_audienceToken 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.
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/api/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/api/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.