Troubleshooting

A single index of common integration and delivery problems.

Request rejected

StatusLikely causeAction
400 malformed_requestEmpty or invalid bodySend valid JSON, urlencoded data or text-only multipart.
403 origin_not_allowedMissing or unlisted OriginAdd the exact canonical origin to the website.
403 verification_failedTurnstile or honeypotRefresh the Turnstile token; ensure the honeypot is empty.
404 form_unavailableWrong ID or disabled form/parentConfirm the public ID and active status.
409 idempotency_conflictKey reused with changed payloadUse a new key for new content.
413 payload_too_largeBody over 64 KiBReduce fields or values.
415 unsupported_media_typeFile, nested object or unsupported typeSend scalar/list fields only.
422 validation_failedForm-specific field rulesReview error.fields.
429 rate_limitedToo many requestsWait for Retry-After.
500 internal_errorUnexpected server failureRetry later and quote the request ID.
503 temporarily_unavailableReadiness, Redis or Turnstile outageRetry with backoff.

CORS errors

  • Confirm the page origin, not the API origin, is allowlisted.
  • Include the scheme and non-default port.
  • http://localhost is 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

  1. Confirm the submission appears in the inbox.
  2. Inspect the delivery status and attempts.
  3. Confirm the worker and scheduler are running.
  4. Check provider quota and credentials.
  5. 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.