Error codes
Stable machine-readable error codes, HTTP statuses and safe field errors.
All public errors use the same shape:
{
"success": false,
"error": {
"code": "validation_failed",
"message": "Check the submitted fields.",
"fields": {
"email": ["Invalid email address."]
}
},
"request_id": "01JY8Z3K4M5N6P7Q8R9S0T1V2W"
}
fields is optional and appears only when a validation error can be attributed to fields.
| Code | HTTP | Meaning |
|---|---|---|
| malformed_request | 400 | The request body was empty, malformed, or contained unsupported structure. |
| origin_not_allowed | 403 | The request origin is missing or not on the form website’s allowlist. |
| verification_failed | 403 | Turnstile verification failed, the token was invalid or expired, or the honeypot was filled. |
| form_unavailable | 404 | The form does not exist, is disabled, or a parent customer/website is disabled. |
| idempotency_conflict | 409 | The same idempotency key was previously accepted with a different payload. |
| payload_too_large | 413 | The request exceeded the 64 KiB body limit. |
| unsupported_media_type | 415 | The content type or payload type is not supported, including file uploads and nested objects. |
| validation_failed | 422 | One or more submitted fields failed validation. Field-level messages are included. |
| rate_limited | 429 | A per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval. |
| internal_error | 500 | An unexpected server error occurred. No internal details are exposed. |
| temporarily_unavailable | 503 | The form is not ready, CAPTCHA verification is temporarily unavailable, or the service cannot safely accept submissions. |
Spam rejection
Honeypot and Turnstile failures return a generic 403 verification_failed. The response never reveals which check failed beyond the safe error code.
Disabled forms
A missing form, a disabled form or a disabled parent returns 404 form_unavailable. The API does not disclose whether a form ever existed.
Internal errors
Unexpected failures return 500 internal_error or 503 temporarily_unavailable with a generic message and a request ID. No configuration, provider detail or stack trace is exposed.