Guides

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

1{
2  "error": {
3    "type": "CONFLICT_ERROR",
4    "code": "INVENTORY_EXHAUSTED",
5    "message": "Only 1 seat available for Orchestra A 101, but 2 requested.",
6    "param": "items[0].quantity",
7    "details": {
8      "availableQuantity": 1,
9      "requestedQuantity": 2
10    }
11  }
12}
FieldRequiredDescription
typeYesError category aligned with HTTP status (see table below)
codeYesMachine-readable error code for programmatic handling
messageYesHuman-readable description (localized per Accept-Language). For display only — don’t switch on this.
paramNoRequest parameter that caused the error (JSON path notation, e.g., items[0].quantity)
detailsNoStructured data for error recovery. Contents vary by error code.

Error Types

Each type maps to an HTTP status code:

TypeHTTP StatusWhen It Happens
INVALID_REQUEST_ERROR400Malformed request, invalid field values, missing required fields
AUTHENTICATION_ERROR401Missing or invalid API key
PAYMENT_ERROR402Payment was refused, or the shopper needs to authenticate before it can go through
PERMISSION_ERROR403Valid API key but insufficient permissions for this operation
NOT_FOUND_ERROR404Resource doesn’t exist or you don’t have access
CONFLICT_ERROR409State conflict (inventory taken, cart already ordered)
RESOURCE_GONE_ERROR410Resource existed but expired (e.g., cart hold timed out)
RATE_LIMIT_ERROR429Rate limit exceeded
API_ERROR5xxServer-side error
SERVICE_UNAVAILABLE503Temporarily can’t serve the request; the same request should succeed on retry

Common Error Codes

Authentication & Authorization

CodeTypeRecovery
INVALID_API_KEYAUTHENTICATION_ERRORCheck API key value, regenerate in the partner portal if needed
INSUFFICIENT_PERMISSIONSPERMISSION_ERRORVerify your API key has the required scope. Manage keys in the partner portal or contact support.

Cart Creation (POST /carts)

CodeTypeRecovery
INVENTORY_EXHAUSTEDCONFLICT_ERRORReduce quantity or choose a different item
INVALID_PRICE_OPTIONINVALID_REQUEST_ERRORRefresh inventory and select a valid price option
OCCURRENCE_NOT_AVAILABLECONFLICT_ERRORChoose a different occurrence
MIXED_OCCURRENCES_NOT_SUPPORTEDINVALID_REQUEST_ERRORAll items must be from the same occurrence

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.

CodeTypeRecovery
CURRENCY_NOT_SUPPORTEDINVALID_REQUEST_ERRORRequest a currency the retailer sells the event in (a valid ISO 4217 code), or omit the currency for base-currency prices
CURRENCY_TEMPORARILY_UNAVAILABLESERVICE_UNAVAILABLEThe currency is sold here but can’t be priced right now (no current exchange rate). Retry shortly, or omit the currency for base-currency prices

Checkout (POST /orders)

CodeTypeRecovery
EXPECTED_TOTAL_MISMATCHINVALID_REQUEST_ERRORRe-fetch cart, display current totals, confirm with customer
CART_EXPIREDRESOURCE_GONE_ERRORCreate a new cart (hold timed out)
CART_ALREADY_ORDEREDCONFLICT_ERRORNavigate to existing order via GET /orders/{orderId}
CART_NOT_ACTIVEINVALID_REQUEST_ERRORCart was deleted — use an active cart
PAYMENT_AUTHENTICATION_REQUIREDPAYMENT_ERRORThe card issuer wants the shopper to authenticate. details.action holds the payment provider’s action as a JSON string — parse it, pass it to your payment SDK to run the challenge, then place the order again with the result under a new Idempotency-Key. Always present on this code.
PAYMENT_DECLINEDPAYMENT_ERRORThe issuer refused the payment. Show message and let the customer try a different payment method. A payment that failed because the provider or network failed is a 5xx instead, since another card won’t help.

General

CodeTypeRecovery
RESOURCE_NOT_FOUNDNOT_FOUND_ERRORVerify the ID is correct; resource may have been deleted
RATE_LIMIT_EXCEEDEDRATE_LIMIT_ERRORWait for Retry-After header value, then retry

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