> ## 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. # Connection webhooks error handling > Errors the Connections API returns to your requests, and the errors you return when receiving a webhook event. # Connection webhooks error handling There are two kinds of errors to handle: 1. **API errors:** what the Connections API returns when you call it to register or manage webhooks. 2. **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`: ```json theme={null} { "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](/white-label/implementation/token-exchange#c-connection-webhooks-api-embedded). | | `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](/white-label/connection-webhooks/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. ## Related * [Verify signatures](/white-label/connection-webhooks/verify-signatures) * [Event payload reference](/white-label/connection-webhooks/payload-reference) * [Connections API reference](/api-reference/connections/connection-webhooks/create-a-connection-webhook)