Errors and retries
The error envelope
Section titled “The error envelope”Every error has the same shape:
{ "error": { "code": "customer_not_found", "message": "Customer was not found in this environment.", "field": null, "request_id": "req_5ac77b5c5d0a4cfa2dc454e7" }}code is stable, so branch on it. field names the offending input for 400 and 422 errors. Include request_id when you contact support. Every response also has an X-Request-Id header.
Status codes
Section titled “Status codes”| Status | Common codes | Meaning |
|---|---|---|
400 |
invalid_json, invalid_request, unknown_field |
malformed JSON or an invalid field; request bodies are strict |
401 |
invalid_api_key |
missing, malformed, unknown or revoked key |
403 |
insufficient_scope |
an evaluate-scope key calling a management endpoint |
404 |
customer_not_found, feature_not_found, … |
not found in this environment |
409 |
feature_key_taken, plan_key_taken, override_overlap, no_draft, idempotency_key_reused, idempotency_in_progress, … |
the request conflicts with the current state |
413 |
request_too_large |
bodies are limited to 1 MiB |
415 |
unsupported_media_type |
send Content-Type: application/json |
422 |
invalid_feature, invalid_subscription_state, feature_not_metered, … |
well-formed but not valid |
429 |
usage_limit_exceeded |
your Account’s API request allowance is used up for this period |
503 |
timeout |
the request hit its deadline; safe to retry |
A missing entitlement is never an error. It’s 200 with granted: false.
What the SDKs retry
Section titled “What the SDKs retry”Both SDKs retry, 2 times by default, with exponential backoff that honours Retry-After:
- network errors and timeouts (10 seconds per attempt by default);
502,503and504;429, exceptusage_limit_exceeded, which lasts until the period resets;409 idempotency_in_progress, when the same request is still running.
Everything else is returned at once.
Idempotency
Section titled “Idempotency”Retrying a mutation is safe because every SDK mutation sends an Idempotency-Key header, reused across retries. If you call the API directly, send your own:
POST /v1/customers/cus_test_0001/subscriptionsIdempotency-Key: 3f0c6a52-…- Keys are kept for 24 hours per environment.
- A repeated request returns the stored response with
Idempotent-Replayed: true. - The same key with a different body is
409 idempotency_key_reused. 5xxresponses aren’t stored, so a retry runs the request again.
Evaluation is read-only and always safe to retry.