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.

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

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

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

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. 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.
  • 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 key per purchase attempt (format: idem_ prefix + random string)
  • 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: idem_a1b2c3d4e5f6

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