Error Handling

All API errors follow a consistent structure for programmatic handling. Parse type and code to determine what happened and how to recover.

This page covers the v3 structured error model. For the v1/v2 error and rate-limit model, see Errors and rate limits on the legacy portal.

Error Response Structure

{
  "error": {
    "type": "CONFLICT_ERROR",
    "code": "INVENTORY_EXHAUSTED",
    "message": "Only 1 seat available for Orchestra A 101, but 2 requested.",
    "param": "items[0].quantity",
    "details": {
      "availableQuantity": 1,
      "requestedQuantity": 2
    }
  }
}

Error Types

Each type maps to an HTTP status code:

Common Error Codes

Authentication & Authorization

Cart Creation (POST /carts)

Cart Vouchers (POST /carts/{cartId}/vouchers)

Currency

Returned when a requested currency — the currency query parameter on reads, or the currency body field on cart create and switch — names a currency the event isn’t sold in, or one it is sold in but that can’t be priced right now. See Currency.

A value that isn’t a three-letter code at all (say usd or EURO) fails field validation first and returns 400 INVALID_FIELD_VALUE; a well-formed code that isn’t a real ISO 4217 currency returns CURRENCY_NOT_SUPPORTED.

When the retailer doesn’t sell the event in the requested currency, the CURRENCY_NOT_SUPPORTED error’s details.supportedCurrencies lists the currencies that would have been accepted, base currency first — the same list each location advertises as availableCurrencies on GET /api/v3/locations.

Checkout (POST /orders)

Every operation on an existing cart — reads included — answers CART_EXPIRED (410) for a cart that is gone (timed out, deleted, or no longer holding inventory) and CART_ALREADY_ORDERED (409) for a cart that became an order, including one since cancelled; its details.orderId names the order to fetch via GET /orders/{orderId}. DELETE /carts/{cartId} is idempotent: re-deleting a cart you already deleted answers 204, while a timed-out or cleared cart still answers the 410.

General

Retry Strategy

Safe to Retry

• 5xx errors — server-side issues are usually transient, including 503 CURRENCY_TEMPORARILY_UNAVAILABLE (a sold currency with no current exchange rate). Retry with exponential backoff (1s, 2s, 4s, max 3 attempts).
• 429 Rate Limit — wait for the Retry-After header value before retrying.
• Network timeouts on POST /orders — always safe when using an Idempotency-Key. The server deduplicates by key, so retrying the same request with the same key will return the existing order if one was created.

Not Safe to Retry (Without Changes)

• 400 errors — fix the request before retrying (wrong field value, missing field, invalid quantity).
• 401/403 errors — fix authentication or permissions (RISK_CHECK_FAILED is the exception — see below).
• 403 RISK_CHECK_FAILED — the order was declined by risk checks. Retrying will not succeed, with the same or a different payment method. Show message and direct the customer to contact customer support.
• 402 PAYMENT_AUTHENTICATION_REQUIRED — run the challenge from details.action first, then place the order again with the result. Use a new Idempotency-Key: the first attempt retired the old one, so reusing it returns 409 IDEMPOTENCY_KEY_FAILED. Nothing was charged, and the cart is still held.
• 402 PAYMENT_DECLINED — the card was refused, and retrying the same card will be refused again. Collect a different payment method, then place the order again with a new Idempotency-Key.
• 409 Conflict — state has changed; re-fetch the resource and adapt.
• 410 Gone — resource is permanently unavailable; start over (e.g., create a new cart).

Idempotency Keys

POST /orders requires an Idempotency-Key header. This makes retries safe:

• Generate a unique UUID v4 per purchase attempt — a value that isn’t a valid UUID v4 is rejected with INVALID_IDEMPOTENCY_KEY
• Reuse the same key when retrying the same checkout
• Same key + same cartId within 24 hours → returns the existing order
• Same key + different cartId → returns 409 Conflict
• Keys expire after 24 hours

POST /api/v3/orders
Idempotency-Key: 3f8c1e2a-9d4b-4f6a-8b21-7c5e0a1d2e34

Forward Compatibility

The API may introduce new error codes and types at any time. To avoid breaking your integration:

• Switch on type for broad error handling (authentication vs validation vs server error)
• Switch on code for specific recovery logic (e.g., CART_EXPIRED → create new cart)
• Use a default/fallback case for unknown type and code values
• Display message to users but never parse it programmatically — it may change