Connection webhooks error handling

There are two kinds of errors to handle:

API errors: what the Connections API returns when you call it to register or manage webhooks.
Delivery errors: what you return to Zapier when it POSTs an event to your callback_url, and how Zapier retries.

API errors

Every error from the endpoints that register and manage webhooks (list, create, retrieve, update, delete) is returned as a JSON body with an errors array. Each error object has this shape:

Field	Type	Required	Description
`code`	string	Yes	Machine-readable identifier for this occurrence.
`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.
`source`	object	No	Reference to the source of the error, for example `{"pointer": "/callback_url"}` for a request-body field or `{"parameter": "event_type"}` for a query parameter.

For example, a validation error identifies the offending field with source:

{
  "errors": [
    {
      "status": 400,
      "code": "invalid_field",
      "title": "Invalid Field",
      "detail": "callback_url must use HTTPS.",
      "source": { "pointer": "/callback_url" }
    }
  ]
}

Read errors[0].code to branch programmatically, and errors[0].detail for the explanation.

HTTP status codes

Status	`code`	Cause	Action
`400`	`invalid_field` (and similar)	A field is missing or invalid: a `callback_url` that is not HTTPS or points at an unsafe target, an unsupported `event_type`, or a `PATCH` with no fields.	Use `errors[0].source` and `errors[0].detail` to find the field, and correct the request.
`401`	`not_authenticated`	The request has no valid credentials.	Send a valid token as `Authorization: Bearer YOUR_TOKEN`. To obtain one, go to Token exchange: Connection Webhooks API.
`403`	`permission_denied`	The token is authenticated but not allowed: the account is not a White Label partner account, or the token is missing the required scope.	Use a White Label partner token with the `connection:webhook:read` or `connection:webhook:write` scope.
`404`	`not_found`	The webhook ID does not exist, or belongs to a webhook your account does not manage.	Confirm the ID and that it belongs to your account.
`409`	`webhook_already_exists`	An active webhook for the same `event_type` already exists. You can have only one active webhook per event type.	Reuse or update the existing webhook, or set it to `is_active: false` first. List your webhooks to find it.
`429`	(rate limited)	You exceeded the rate limit.	Check the `Retry-After` response header and wait that many seconds. Apply exponential backoff.

Delivery errors

When Zapier POSTs an event to your callback_url, the status you return controls whether Zapier retries.

Success (2xx): the delivery is acknowledged and not retried.
Retryable failure (429 or 5xx): the delivery is retried later. A timeout or connection error is also retried.
Permanent failure (any other 4xx): the delivery is not retried. Return one only when the delivery is genuinely unprocessable, such as a signature that does not verify.

Verify the signature before you act on any delivery. For the steps, go to Verify signatures.

Retries and Retry-After

Retryable failures are retried a few times with increasing backoff, over roughly 25 minutes. If every attempt fails, the event is dropped and not delivered again. If your endpoint returns a 429 or 5xx with a Retry-After header, Zapier honors it as the delay before the next attempt, in place of the default backoff. Only the integer-seconds form is honored (for example, Retry-After: 120); the HTTP-date form is ignored, and Zapier falls back to its default backoff. The delay is capped at 600 seconds (10 minutes). Because a delivery can be retried, the same event can arrive more than once. Deduplicate on the webhook-id header and make your handler idempotent.

Use cases

Implementation

Trigger Inbox