Skip to content

Errors and retries

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 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.

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, 503 and 504;
  • 429, except usage_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.

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/subscriptions
Idempotency-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.
  • 5xx responses aren’t stored, so a retry runs the request again.

Evaluation is read-only and always safe to retry.