API errors

Every error from the SeatLayer API has the same shape: a JSON object whose first key, error, is a stable machine code. Branch on error (and code when present), never on message.

The error body

{
  "error": "not_found"
}

{
  "error": "order_edit_in_progress",
  "code": "order_edit_in_progress",
  "retryable": true,
  "conflicts": [{ "label": "A-12", "status": "blocked" }]
}

Routes add their own detail fields next to these, for example conflicts, issues, maxBytes, or currentUpdatedAt. Treat unknown fields as extra information, not as a different error.

The OpenAPI document lists the exact error codes each operation can return. This page groups them so you can write one handler.

Status codes

Codes by area

Authentication and access

Validation

Events and charts

Holds, booking, and inventory

Idempotency

See idempotency and conflicts.

Seasons and Performance Groups

Long Season and Performance Group operations can answer 202 Accepted with Location and Retry-After. That is progress, not an error: poll the Location until the state is terminal.

Season seats

Season seats are the seats a season sets aside on every date. While they are set aside, some changes would make them wrong, and a few changes aren’t possible in block mode yet. Both are refused, and nothing changes.

Old SDK versions surface these through their generic API error, with code.

Webhooks

Service-wide

Which errors to retry

• Reads (GET): retry on connection errors, 408, 429, and 5xx, with backoff. An event’s report, objects, log, and seat history answer 503 with code: event_temporarily_unavailable and Retry-After: 1 while the event’s inventory restarts; repeat the read after that delay.
• Writes with Idempotency-Key: retry on the same failures with the same key. The first result is replayed, so nothing happens twice.
• Writes without idempotency: holds, blocks, and most inventory changes. Retry 429 after Retry-After, because it did nothing. A 503 whose code is event_temporarily_unavailable means the event’s inventory did not answer in time, and the change may still have been made. Before you repeat a hold, block, extend, or best-available call, read the hold or the seats. After a timeout or 500, also read the current state before trying again.
• Book: on a 503 with retryable: true, wait for Retry-After and send the same book request once more, with the same bookingRef. One reference cannot make a second sale, so this repeat is always safe. If it answers 503 again, keep the order as payment in progress and retry it from your queue.
• 409 with retryable: true: wait briefly and send the same request.
• Every other 4xx: do not retry unchanged. Fix the request, pick other seats, or show the conflict to the operator.

A booking call keyed by one bookingRef is safe to repeat: the same reference cannot create a second sale. Releasing a hold is safe to repeat too: it only frees seats still held under that holdId. See idempotency and conflicts.