Webhooks error codes
Every public API error code emitted by Webhooks, with its HTTP status, its type and a page per code.
Error codes emitted by Webhooks. Each code links to its own page with the cause and the action to take.
| Code | Type | HTTP | Description |
|---|---|---|---|
account_webhook_endpoint_limit_reached | invalid_request_error | 422 | The account reached the number of account webhook endpoints its tier allows in that environment. The cap is counted per account and per environment (live or test) and includes disabled endpoints: only deleting an endpoint frees a slot. |
addon_required | payment_required_error | 402 | Creating webhook endpoints requires a plan that includes them: for company endpoints, the Developer API add-on of the company; for account endpoints, the plan of the payer of the account. That subscription is missing here — the free tier allows zero endpoints. |
api_version_invalid_format | invalid_request_error | 422 | The payload version of the endpoint is not a YYYY-MM-DD date. |
api_version_unsupported | invalid_request_error | 422 | The payload version is well formed but is not among the ones the platform serves. |
custom_header_blocklisted | invalid_request_error | 422 | One of the custom headers is reserved: the HTTP layer manages it (host, content-type, content-length, user-agent), Factuarea sends it as part of the signed contract (factuarea-*), or the proxy owns it (x-forwarded-*). |
custom_header_value_too_long | invalid_request_error | 422 | The value of a custom header exceeds 1024 characters. |
invalid_url_target | invalid_request_error | 422 | The destination host is not a publicly reachable address, so we refuse to deliver to it: private ranges (RFC 1918), loopback, link-local, CGNAT (100.64.0.0/10), IPv6 ULA (fc00::/7) and multicast are all rejected. Despite the wording of the message, the restriction applies in every environment, not only in production. |
replay_delivery_not_retryable | invalid_request_error | 422 | Only failed deliveries can be replayed. A delivery that succeeded, or one still in flight, has nothing to resend. |
replay_event_expired | invalid_request_error | 422 | The event behind the delivery was purged by the 30-day retention policy, so there is no payload left to resend. |
timeout_seconds_out_of_range | invalid_request_error | 422 | timeout_seconds falls outside the range 1 to 30 seconds. |
too_many_custom_headers | invalid_request_error | 422 | The endpoint declares more than 20 custom headers. |
webhook_delivery_not_found | not_found_error | 404 | The identifier does not match any delivery attempt, or the delivery falls outside the retention window kept for the history. |
webhook_endpoint_degraded | invalid_request_error | 422 | The endpoint is degraded after repeated delivery failures, so test pings are refused while it stays in that state. |
webhook_endpoint_not_found | not_found_error | 404 | The identifier does not resolve to any webhook endpoint of the authenticated company. |
webhook_secret_recently_rotated | invalid_request_error | 422 | The signing secret was rotated less than five minutes ago. The grace window lets your receiver accept both secrets during the switch; rotating again inside it would invalidate signatures still in flight. It answers as a 422 business_rule_violation with error.subcode webhook_secret_recently_rotated; it is not a request limit and consumes no rate-limit bucket. |
Related
Error codes by category
Find an error by the category that emits it.
Full reference table
All codes, HTTP statuses, types and descriptions in one reference.
Error model
Interpret the error envelope and handle errors by code.