Pages · Errors & idempotency

Errors, idempotency and pagination

The error shape, stable codes, safe retries and list pages.

Errors

Every failure, including 404 and 405, returns the same shape, and every response carries a Request-Id header. Codes are stable strings: branch on code, show message to developers, and quote request_id when you contact us.

{
  "error": {
    "code": "invalid_sha256",
    "message": "…",
    "field": "sha256",
    "request_id": "req_4f0c8e2a9b7d4c1e8a3f6b2d0e9c7a15"
  }
}
StatusMeaning and codes
400The body is not JSON, or the Idempotency-Key is missing or malformed.
401The API key is missing or not valid (missing_api_key, invalid_api_key).
403The key lacks a scope (insufficient_scope), or is a live key (live_mode_unavailable).
404No such resource for this key, or no such path.
409The resource's state does not allow this (order_not_revisable, quote_already_used, upload_incomplete, too_many_endpoints, endpoint_disabled, delivery_in_flight, payment_method_required, partner_terms_required).
413The body is over 2 MiB (body_too_large). It may be refused only after more of it was sent.
415The body is not application/json.
422The request is invalid; field names the problem, code says what it is.
429Too many requests for this API key (rate_limited): 300 a minute across all endpoints. Wait the number of seconds in Retry-After, then retry with the same Idempotency-Key.
500Our error. Retrying is safe with the same Idempotency-Key.

Other codes in the contract: format_unavailable (no price for a format in your mode), idempotency_mismatch, order_released (409, with exception_id), invalid_url and billing_unavailable (503). A 422 names the problem in field.

Idempotency

  • Writes that change things require an Idempotency-Key header (1–255 printable ASCII characters); POST /quotes accepts one. Enabling, disabling and billing setup take none.
  • Keys are scoped to your account, mode and operation, and kept for 30 days.
  • Repeating a request with the same key returns the original response, marked Idempotent-Replayed: true.
  • Reusing a key for a different request returns 422 idempotency_mismatch.
  • A request that failed is not stored, so you can correct it and retry with the same key. Finalize is the exception: see Uploads.
  • A 500 is our error. Retrying is safe with the same key.

Generate one key per logical operation (a UUID saved with your own record works well) and reuse it for every retry of that operation.

Pagination

List endpoints return { "object": "list", "data": […], "has_more": … }. Pass limit (1–100) and, for the next page, starting_after with the last id of the page you have. GET /events for one order pages by after_sequence instead.

Other limits

  • Each API key can make 300 requests a minute across all endpoints. Past that you get 429 rate_limited with a Retry-After header in seconds: wait that long, then retry (with the same Idempotency-Key for writes).
  • Request bodies are limited to 2 MiB (413 body_too_large). Upload files go to the signed URL, not through the API.
  • Bodies must be application/json (415 otherwise).
  • Paths have no trailing slash: /orders/ is a 404, not a redirect.
  • Amounts are integers in the currency's minor unit (cents for usd), with an explicit lowercase currency.