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 |
|---|---|---|---|
addon_required | payment_required_error | 402 | Creating webhook endpoints belongs to the Developer API add-on, and the company does not have it active — 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 | rate_limit_error | 429 | 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. |
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.