API reference
Errors, idempotency, and rate limits
Handle safe error envelopes, retries, idempotency conflicts, quotas, and challenges without guessing outcomes.
Errors, idempotency, and rate limits
Errors use a stable machine code, a safe message, and a request correlation ID. Never parse human text as protocol. A write that times out is unknown, not failed: query by its idempotency key before retrying.
| HTTP | Meaning | Client action |
|---|---|---|
400 / 422 | Invalid request or domain validation | Correct the submitted fields; do not retry unchanged. |
401 | Missing, expired, or revoked authentication | Reauthorize safely; never widen CORS. |
403 | Scope, role, store, market, consent, or capability denied | Stop and request an authorized grant. |
404 | Hidden or absent resource | Do not enumerate identifiers. |
409 / 412 | Idempotency or optimistic-version conflict | Reload the authoritative resource and reconcile. |
429 | Rate limit or risk challenge | Honor Retry-After; complete a challenge only when instructed. |
5xx | Service unavailable or unknown outcome | Preserve intent, back off, then reconcile. |
Limits are evaluated by app, installation, tenant/store, route, and risk tier—not only IP. Turnstile is currently planned/not enabled. Even after future Siteverify validation, it proves only one bot-challenge result. cf_clearance is not login state and cannot bypass OAuth scopes, tenant ownership, quotas, or sensitive-operation step-up.