Errors

Every error response has this shape. Each endpoint lists the errors it can return.

• status_codeinteger

  HTTP status code, repeated in the body.

• errorstring

  Short label matching the HTTP status.

• codestring

  Stable machine-readable error code in snake_case. Branch on this, never on message.

• messagestring

  What went wrong and how to fix it, written to be shown to a person.

• detailsobjectOptional

  Extra structured context when it helps, for example the list of invalid fields. When a refusal is fixed in the 3DAPI dashboard (billing, store, compliance or plan), fix_url links to the page that fixes it.

{
  "status_code": 404,
  "error": "Not Found",
  "code": "product_not_found",
  "message": "Product prd_bfP0GSqKoZFrD72H5Os0rc7HV9XP6eQJu was not found.",
  "details": {}
}

Branch on code, never on message. These come up across many endpoints; the rest are listed on the endpoint that returns them.

validation_failed

A field is missing or has the wrong type or value. details lists the fields.

missing_scope

The API key does not carry the scope this endpoint needs.

invalid_cursor

A pagination cursor was edited or is not from this list.

invalid_expand

An expand[] path is not offered by this endpoint.

idempotency_key_reused

The same Idempotency-Key was sent with a different body.

plan_limit_reached

Your plan limit is reached. details.fix_url points at upgrading.

payment_failed

The charge to your saved card failed; nothing was created.

insufficient_balance

The wallet balance does not cover the purchase.

A 4xx other than 429 will fail again until the request changes: read code and fix the request. A 429 or 503 is temporary: wait and retry with exponential backoff, and send the same Idempotency-Key when retrying a write.

Every endpoint except the health check can answer 429 with code rate_limited; wait for the number of seconds in the Retry-After header. The limits are in Rate limits.

Each code with the statuses it comes with and the endpoints that return it. The OpenAPI document lists them per response in x-error-codes.