Troubleshooting
A single index of common integration and delivery problems.
Request rejected
| Status | Likely cause | Action |
|---|---|---|
400 malformed_request | Empty or invalid body | Send valid JSON, urlencoded data or text-only multipart. |
403 origin_not_allowed | Missing or unlisted Origin | Add the exact canonical origin to the website. |
403 verification_failed | Turnstile or honeypot | Refresh the Turnstile token; ensure the honeypot is empty. |
404 form_unavailable | Wrong ID or disabled form/parent | Confirm the public ID and active status. |
409 idempotency_conflict | Key reused with changed payload | Use a new key for new content. |
413 payload_too_large | Body over 64 KiB | Reduce fields or values. |
415 unsupported_media_type | File, nested object or unsupported type | Send scalar/list fields only. |
422 validation_failed | Form-specific field rules | Review error.fields. |
429 rate_limited | Too many requests | Wait for Retry-After. |
500 internal_error | Unexpected server failure | Retry later and quote the request ID. |
503 temporarily_unavailable | Readiness, Redis or Turnstile outage | Retry with backoff. |
CORS errors
- Confirm the page origin, not the API origin, is allowlisted.
- Include the scheme and non-default port.
http://localhostis allowed only in explicit local development.- Do not use wildcards.
- Check error responses for CORS headers; they are present for allowed origins.
Turnstile errors
- Confirm the site key and action.
- Confirm the widget is rendered on the customer website.
- Reset the widget after success.
- Do not reuse a token.
- Do not retry an invalid token automatically.
No email
- Confirm the submission appears in the inbox.
- Inspect the delivery status and attempts.
- Confirm the worker and scheduler are running.
- Check provider quota and credentials.
- Resend manually if the delivery is failed or exhausted.
Documentation corrections
The docs are maintained in version control. When the API changes, update the OpenAPI artifact, the relevant page and the changelog.