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_request400The request body was empty, malformed, or contained unsupported structure.
origin_not_allowed403The request origin is missing or not on the form website’s allowlist.
verification_failed403Turnstile verification failed, the token was invalid or expired, or the honeypot was filled.
form_unavailable404The form does not exist, is disabled, or a parent customer/website is disabled.
idempotency_conflict409The same idempotency key was previously accepted with a different payload.
payload_too_large413The request exceeded the 64 KiB body limit.
unsupported_media_type415The content type or payload type is not supported, including file uploads and nested objects.
validation_failed422One or more submitted fields failed validation. Field-level messages are included.
rate_limited429A per-IP, per-form, or global rate limit was exceeded. Retry after the Retry-After interval.
internal_error500An unexpected server error occurred. No internal details are exposed.
temporarily_unavailable503The 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.