API errors and response handling

1. Read status before data

Successful submit and draft-create requests return 201; draft updates and reads return 200; browser preflight returns 204. A native submission with an approved redirect can return 303. Error responses generally contain ok: false and error.message; error.details may be an array, an object, or absent on server errors. Proxies can return non-JSON errors, so JSON parsing itself must be allowed to fail.

{
  "ok": false,
  "error": {
    "message": "Too many submissions. Please try again later.",
    "details": { "retry_after": 60 }
  }
}

2. Correct credentials and access

401 means a missing, invalid, or revoked read key. 402 can mean the plan does not include uploads. 403 can indicate an origin restriction or a final draft belonging to another form. 404 can indicate a paused, archived, or unknown form, an inaccessible submission, or an unavailable draft. Check the endpoint and credential before retrying.

3. Correct the request

410 indicates an expired draft. 413 means a request, field payload, or synchronous export exceeds its size limit. 422 covers invalid fields, CAPTCHA, uploads, redirects, spam rejection, or unsupported read filters. Read error.message to identify the cause. There is no single field-error map shared by every endpoint. Fix the request or form configuration before trying again.

4. Handle throttling and service failures

429 can mean request throttling, monthly quota, or draft/spam storage limits. When supplied, Retry-After and error.details.retry_after are seconds to wait. 500 or 503 can mean a service or storage problem. Use bounded retries with increasing delays for reads, and preserve the original idempotency key and payload for final submissions. A network error or server error can leave receipt uncertain; blindly posting again can create duplicates. See Idempotent submissions.

5. Collect useful diagnostic details

Record the method, endpoint pattern, UTC time, HTTP status, and sanitized error message. Include X-Request-Id if present. Do not log bearer keys, draft tokens, reset links, signed attachment URLs, or private field bodies. In the browser, use the Network panel to inspect the failed request and any OPTIONS request. See the matching guide in Troubleshooting before escalating a persistent failure through the site’s support contact.

• Rate limits and monthly usage
• Validation and upload errors
• Fixing CORS errors