Document / EN

Error codes

Every error response has the same shape. Match on error: it is stable and listed below. code is an optional, finer detail code (UPPER_SNAKE) used by the dashboard for localized messages; message is English text for logs — never match on it. Quote the x-request-id response header to support.

json

{ "error": "validation_error", "message": "key must be 1 to 100 characters …", "code": "ERR_VALIDATION" }

Kinds and TS SDK classes

Kind	HTTP	TS SDK class
Validation (`validation`)	400, 413, 422	`SeatsChartValidationError`
Authentication and permission (`auth`)	401, 403	`SeatsChartAuthError`
Not found (`not_found`)	404	`SeatsChartNotFoundError`
Conflict (`conflict`)	409, 410, 412	`SeatsChartConflictError`
Plan and billing (`payment`)	402	`SeatsChartHttpError`
Rate limit (`rate_limit`)	429	`SeatsChartRateLimitError`
Server (`server`)	500, 502, 503	`SeatsChartServerError`

The HTTP status picks the TS SDK class; every class extends SeatsChartHttpError, so existing instanceof checks keep working.

A request that gets no response within the client's timeoutMs (30 s per attempt by default) throws SeatsChartTimeoutError with code timeout. It has no HTTP status and does not extend SeatsChartHttpError; the server SDKs raise their own typed timeout error (Server SDKs).

Codes

Descriptions match the OpenAPI catalog (components.schemas.ApiError).

`error`	Kind	Meaning
`bad_request`	Validation	The request is malformed or inconsistent (see `message`).
`validation_error`	Validation	A field failed validation: schema (TypeBox) or business rule; `setting` / `property` name the field when known.
`validation_failed`	Validation	Map or chart content failed the designer validation rules (`issues`).
`invalid_body`	Validation	The request body could not be parsed as JSON.
`invalid_parameters`	Validation	Query or path parameters are invalid.
`payload_too_large`	Validation	The request body exceeds the size limit of the route (413).
`objects_not_found`	Validation	Objects named in the request do not exist in the event (`objects`).
`not_season_member`	Validation	Events must belong to the parent season (`eventIds`).
`quantity_required`	Validation	A general-admission quantity is required.
`for_sale_edit_conflict`	Validation	An object or category is listed in both `forSale` and `notForSale` (`objects`, `categories`).
`ticket_type_required`	Validation	The category sells several ticket types; pass one.
`ticket_buyer_id_required`	Validation	Ticket buyer validation is on: pass a registered ticket buyer id.
`idempotency_key_required`	Validation	This route requires an `Idempotency-Key` header.
`invalid_code`	Validation	The two-factor or recovery code is not valid.
`invalid_order_id`	Validation	The order id is not valid.
`invalid_signature`	Validation	The webhook signature could not be verified.
`empty_chart`	Validation	The chart has no seats or general-admission areas.
`setup_expired`	Validation	The two-factor setup expired; start again.
`ga_table_whole`	Validation	Tables booked as a whole cannot be booked by seat.
`ga_area_whole`	Validation	The area is sold as a whole: quantity is its people (fixed: the capacity; variable: minOccupancy..capacity), never part of its places.
`unauthorized`	Authentication and permission	Missing or invalid credentials (401): send `x-api-key` or `Authorization: Bearer`.
`forbidden`	Authentication and permission	Authenticated, but not allowed (role, workspace or route policy).
`insufficient_scope`	Authentication and permission	The API key lacks the scope this route requires (`requiredScope`).
`workspace_deactivated`	Authentication and permission	The workspace is deactivated: API keys and viewer tokens are refused.
`channel_forbidden`	Authentication and permission	The objects belong to an inventory channel the caller is not authorized for.
`ga_places_to_channels_disabled`	Authentication and permission	Assigning GA places to channels is turned off for this workspace.
`ticket_buyer_required`	Authentication and permission	Ticket buyer validation is on: the buyer token must carry a ticket buyer id.
`ticket_buyer_not_registered`	Authentication and permission	The ticket buyer id is not registered in this workspace.
`ticket_buyer_mismatch`	Authentication and permission	The hold belongs to another ticket buyer.
`pending_sign_in_expired`	Authentication and permission	The pending two-factor sign-in expired; sign in again.
`two_factor_required_by_workspace`	Authentication and permission	The workspace requires two-factor authentication.
`two_factor_enrollment_required`	Authentication and permission	Enrol two-factor authentication before continuing.
`not_found`	Not found	The resource (or route) does not exist in this workspace.
`event_not_found`	Not found	No event with this id or key exists in this workspace.
`draft_not_found`	Not found	The map has no draft.
`extra_data_not_published`	Not found	The workspace does not publish extraData to buyers (Settings → Seat data for buyers).
`conflict`	Conflict	The request conflicts with the current state (see `message` / `code`).
`idempotency_conflict`	Conflict	The `Idempotency-Key` was used with a different request.
`inventory_conflict`	Conflict	Objects are not in the state the operation needs (held, sold, not for sale…).
`hold_token_conflict`	Conflict	The hold token is expired or belongs to another session.
`booking_limit_exceeded`	Conflict	The organizer booking limits refuse the hold or confirmation (`limit`, `current`, `requested`, `kind`).
`buyer_limit_exceeded`	Conflict	The buyer reached the per-buyer limit of a sales rule.
`quote_required`	Conflict	A new confirmation needs a `quoteId` (POST /api/quotes).
`quote_mismatch`	Conflict	The quote or payment attestation does not match the confirmation.
`quote_conflict`	Conflict	Any other quote conflict.
`price_mismatch`	Conflict	Declared amounts do not match the price table.
`currency_mismatch`	Conflict	The currency does not match the event currency.
`price_table_missing`	Conflict	The event has no synced price table.
`lot_sold_out`	Conflict	Every lot of the lot plan is sold out.
`insufficient_inventory`	Conflict	Not enough free seats or places for the request.
`insufficient_free_places`	Conflict	Cannot withhold more GA places than are free (`areas`).
`ga_area_occupancy_locked`	Conflict	A publish would change how areas with sold or held places are sold (`objects`).
`illegal_previous_status`	Conflict	An object is not in the expected previous status.
`ambiguous_label`	Conflict	A label matches several objects; use ids (`labels`).
`chart_invalid`	Conflict	The published chart has error-level validation issues (`issues`).
`chart_archived`	Conflict	The chart is archived.
`chart_not_published`	Conflict	The chart has never been published.
`not_published`	Conflict	The map has not been published yet.
`geometry_not_published`	Conflict	The event geometry has not been published yet.
`chart_switch_conflict`	Conflict	The event cannot switch charts while objects are held or sold.
`structural_mismatch`	Conflict	Held or sold objects have no counterpart in the target chart (`orphanedObjects`).
`draft_conflict`	Conflict	The draft changed since it was read.
`category_exists`	Conflict	A category with this key or label already exists.
`category_in_use`	Conflict	The category is still used by objects.
`event_key_taken`	Conflict	Another event of the workspace uses this key.
`chart_key_taken`	Conflict	Another chart of the workspace uses this key.
`season_key_taken`	Conflict	Another season of the workspace uses this key.
`partial_season_key_taken`	Conflict	Another partial season of this season uses this key.
`ambiguous_season_key`	Conflict	Several partial seasons use this key; pass the partial season id.
`event_sale`	Conflict	The event has sales; the change is refused.
`season_booked`	Conflict	The season objects are booked.
`season_chart_mismatch`	Conflict	The event chart differs from the season chart.
`season_has_no_chart`	Conflict	The season has no chart yet.
`season_source_event`	Conflict	The season source event cannot take this change.
`season_source_required`	Conflict	The season has no source event.
`season_status_conflict`	Conflict	The season status change conflicts with member statuses.
`season_status_overridden`	Conflict	The event overrides the season status of these objects.
`season_bookings_not_propagated`	Conflict	The season does not propagate bookings: season bookings go to its source event, which this call cannot reach.
`limit_exceeded`	Conflict	A resource limit was reached (for example partial seasons per season).
`too_many_events`	Conflict	Too many events for one call.
`last_active_workspace`	Conflict	The last active workspace cannot be deactivated.
`own_workspace`	Conflict	The action cannot target your own workspace.
`sandbox_limit_reached`	Conflict	The workspace already has its maximum number of sandboxes (`limit`); delete one first.
`two_factor_not_enabled`	Conflict	Two-factor authentication is not enabled on this account.
`two_factor_already_enabled`	Conflict	Two-factor authentication is already enabled.
`checkout_not_complete`	Conflict	The checkout session is not complete.
`scan_route_retired`	Conflict	This route was retired (410); see `message` for its replacement.
`listing_incomplete`	Conflict	A listing sold as a whole is only partly in the confirmation (`listing`, `missingObjects`).
`listing_has_holds`	Conflict	Objects of the listing are held: the change waits until the holds end (`heldObjects`).
`listing_object_conflict`	Conflict	An object already belongs to another active listing (`objects`).
`listing_objects_removed`	Conflict	A map publish or chart switch would remove objects of active listings (`listings`: id, key, `removedObjects`); withdraw them first or retry with `withdrawAffectedListings`.
`listing_key_taken`	Conflict	Another listing of the event uses this key.
`listing_closed`	Conflict	The listing is sold or withdrawn; only active listings change.
`listing_type_exists`	Conflict	A listing type with this key already exists.
`listing_type_in_use`	Conflict	Active listings use this listing type.
`plan_limit_exceeded`	Plan and billing	The plan limit is reached (402); upgrade to continue.
`quota_exceeded`	Plan and billing	The monthly quota is used up.
`no_subscription`	Plan and billing	The workspace has no subscription.
`no_customer`	Plan and billing	The workspace has no billing customer.
`test_workspace_not_billable`	Plan and billing	Test workspaces are not billed.
`rate_limit_exceeded`	Rate limit	Too many requests (429): wait for `Retry-After` seconds.
`too_many_attempts`	Rate limit	Too many attempts; wait before retrying.
`internal_error`	Server	Unexpected server error (500); retry with the same `Idempotency-Key`.
`service_unavailable`	Server	A dependency is temporarily unavailable (503); retry.
`redis_unavailable`	Server	The in-memory store is unavailable (503); the outcome may be uncertain, retry with the same operation identity.
`service_draining`	Server	The instance is shutting down (503); retry.
`stripe_not_configured`	Server	Billing is not configured on this server.
`checkout_failed`	Server	The billing checkout could not be created.
`portal_failed`	Server	The billing portal could not be opened.
`confirm_failed`	Server	The confirmation could not be completed; retry with the same `Idempotency-Key`.
`extraction_failed`	Server	The chart image could not be analysed.
`webhook_handler_failed`	Server	The billing webhook handler failed.

Deprecated aliases

Older versions of some routes returned these spellings. Responses now carry the canonical code; if your client compares against an old value, normalize with canonicalErrorCode() (TS SDK) — the SDK's typed errors already accept both.

Deprecated	Canonical
`validation`	`validation_error`

Detail codes (`code`)

Stable as well. The ERR_ prefix is historical: codes added without it keep their names.

ERR_BAD_REQUEST, ERR_NOT_FOUND, ERR_UNAUTHORIZED, ERR_FORBIDDEN, ERR_CONFLICT, ERR_VALIDATION, ERR_SERVICE_UNAVAILABLE, ERR_INTERNAL, ERR_RATE_LIMIT, ERR_PLAN_LIMIT, ERR_IDEMPOTENCY_CONFLICT, ERR_SEAT_LOCKED, ERR_SEAT_UNAVAILABLE, ERR_SEAT_SOLD, ERR_SEAT_HOLD_REQUIRED, SEAT_NOT_FOR_SALE, SEAT_CHANNEL_FORBIDDEN, BA_NO_HOLDABLE_WINDOW, ERR_SEATS_NOT_FOUND, ERR_EVENT_NOT_FOUND, ERR_CHART_NOT_FOUND, ERR_CHART_NOT_ARCHIVED, ERR_CHART_HAS_EVENTS, ERR_AUTO_PUBLISH_CHART_HAS_EVENTS, ERR_CHART_TAG_INVALID, ERR_CHART_TAG_LIMIT, ERR_CHART_VERSION_NOT_FOUND, ERR_MAP_VERSION_NOT_FOUND, ERR_MAP_NEVER_PUBLISHED, ERR_DRAFT_NOTHING_TO_DISCARD, ERR_THUMBNAIL_EXISTS, ERR_THUMBNAIL_INVALID, ERR_NAME_EMPTY, ERR_GA_HOLD_INVALID, ERR_GA_HOLD_MISSING, ERR_GA_CAPACITY, ERR_GA_AREA_NOT_FOUND, GA_NOT_FOR_SALE, GA_CHANNEL_FORBIDDEN, ERR_HOLD_SERVICE_UNAVAILABLE, ERR_PUBSUB_FAILED, ERR_CHANNEL_LIMIT, SEASON_SOURCE_REQUIRED, SEASON_CHART_MISMATCH, SEASON_EVENT_ALREADY_MEMBER, SEASON_MEMBER_CAP, ERR_SEASON_NOT_FOUND, ERR_PARTNER_SCOPE, ERR_FORBIDDEN_ROLE, ERR_SANDBOX_SCOPE