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. |
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. |