Skip to content

More

Errors

Reference only. Not a decision unless cited in product/DECISIONS.md.

Errors

How /v1 tells you something failed, and what to do next.

Who this is for

Anyone integrating the headless API.

Envelope

Error responses use OpenAPI ApiError:

{
  "success": false,
  "error": "human-readable message or stable code string"
}

Success responses use { "success": true, "data": … }. Always branch on success and HTTP status. Confirm the exact shape in OpenAPI before parsing in production.

There is no separate machine code field in the current public ApiError schema — treat error as the string you log and map.

HTTP status guide

StatusMeaning
400Bad request or validation failure
401Missing or invalid credential
403Valid credential, wrong scope or role
404Not found (also used for enumeration-safe cross-tenant misses)
409Conflict (including some idempotency / state clashes). Checkout POST /v1/orders/preview-total and order create also use 409 capacity_unavailable when qty is above remaining sellable.
422Semantic / business validation failure
429Rate limited; back off and retry
5xxServer fault; retry with backoff

Scan business outcomes often return HTTP 200 with a result_code in the body. Do not treat every non-admit as a transport error.

Checkout (preview and order create)

What a guest can hit on POST /v1/orders/preview-total, POST /v1/orders and POST /v1/orders/{orderId}/payments/start. Map each error to your own guest copy. Never show the raw string. Some error values are short sentences rather than codes (for example quantity exceeds the maximum per-order limit); match them exactly.

errorCreatePreviewWhen
capacity_unavailable409409Quantity is above what is still sellable. This is also how a sold-out ticket type answers
addon_sold_out409An add-on in the cart does not have enough left
event_not_published, sale_not_started, sale_ended400422A show in the cart is not on sale now: its status is not on sale (draft, paused, sold out or completed), or now is before or after its sale window
ticket sales have not started yet, ticket sales have ended for this tier400422A ticket type in the cart is before or after its own sale window
quantity is below the minimum per-order limit, quantity exceeds the maximum per-order limit400422The cart is below or above a ticket type's per-order limit, or above an add-on's
event_cancelled400422A show in the cart was cancelled
cross_production_lines400422 ¹A type that cannot sell on this order's show (another series, or a pass that does not admit it)
coupon_*400400Coupon refused. See the list in Headless API
below_minimum_charge400400The card or bank (ACH) total is 1 to 49 cents, which cannot be charged. A cart with a coupon gets coupon_below_minimum_charge instead
total_changed409You sent displayed_total_cents and the real total differs. The body carries the real total_cents
order_payment_in_flight409The buyer's earlier hold on this show is already paying
checkout_hold_release_pending503The buyer's earlier hold on this show could not be closed yet and Stripe could not confirm its payment is dead. Nothing was created or charged. Retry after Retry-After seconds
payout_not_ready409The organizer's payment setup cannot take charges, on any payment method (pay at the door included). On create nothing is reserved
hold_expired409Payment start on a hold that is over, or an order create whose key (or reused hold) is over, or was an unseated hold on the other payment rail (released). Start checkout again
idempotency_key_reused409Payment start with a key that already started another order, or an order create whose other-rail hold could not be released. Retry with a fresh key
order_already_placed409Order create whose key belongs to a parked, paid or paying order on the other payment rail (card vs cash_at_entry). That order stands; nothing new is created
checkout_hold_payment_method_locked409Order create on the other payment rail while the buyer holds reserved seats on a checkout hold. The seats stay held: finish on the first rail, or cancel the hold and pick seats again
cash_at_entry_not_enabled, cash_at_entry_capacity, cash_at_entry_pending_limit422Pay at the door is off for this event, or its limit is reached
ach_unavailable400Bank payment is not on for this organizer
payment_attempts_exceeded429Too many declined cards in the last 60 minutes from this checkout session (5), this email (5) or this IP address (10)
order_create_attempts_exceeded429More than 10 order creates for this show from one purchaser email and IP address in 10 minutes
rate limit exceeded429429Per buyer session: 20 order creates and 25 payment starts per minute. Per IP: 60 order creates per show per minute, 30 previews per show per minute, 60 payment starts per minute. Seat holds (POST /v1/seats/hold): 60 per buyer session and 120 per IP per minute (Rate limits)
fee_schedule_missing, fee_schedule_unavailable503503AXYN could not load the fees for this sale. Retry later
payout_check_unavailable503AXYN could not check the organizer's payouts. On create nothing is reserved. Retry later
event not found, event_not_found400 / 404404No event with that venue_event_id. Create answers 400 event_not_found when it misses the event early, and 404 otherwise

A blank Preview cell means preview does not return that code. Preview never checks add-on stock; only create does.

¹ Preview does not name this case yet: it answers 422 with failed to create order. Order create returns cross_production_lines.

POST /v1/orders/{orderId}/payments/start answers payout_not_ready, payout_check_unavailable, hold_expired, idempotency_key_reused, below_minimum_charge and payment_attempts_exceeded with the statuses above. It checks payouts again after the hold exists, so payout_not_ready and payout_check_unavailable from payment start leave the hold in place. Request errors use the usual statuses: 400 for a missing or bad Idempotency-Key, a bad orderId or an unsupported payment method, 401, 403, 404 order not found, and 429 when rate limited. On an order that is already paid it returns the tickets, or 500 qr_finalize_failed if they cannot be read. Any other failure while starting the Stripe payment is a 502.

Seating publish (422)

For section_and_type and reserved_seat only. general does not use these codes. Full flow: Organizer seating.

errorWhen
seating_not_readyPublish before POST .../seating:ready with { "ready": true }
seating_inventory_requiredReady/publish with no seats (reserved) or no sections (section)
seating_tiers_requiredReserved sellable seat has no ticket type
layout_not_seatedApply / save / seating-ready called on GA
overwrite_confirm_requiredHouse already saved; send confirm_overwrite: true
house_emptyApply with no venue house geometry
venue_requiredSeated event has no linked place

Pay at the door needs Stripe

POST /v1/events and PATCH /v1/events/{eventId} with cash_at_entry_enabled: true, when that turns pay at the door on. AXYN's fee on door cash comes out of the organizer's Stripe balance, so the organizer's payment setup must be able to take charges first. Sending true again on an event that already takes pay at the door is not refused.

errorHTTPWhen
pay_at_door_needs_stripe422The payment setup cannot take charges. blocker says why (connect_required, connect_incomplete, connect_missing_on_platform, …)
payout_check_unavailable503AXYN could not check the payment setup with Stripe. Nothing was saved. Retry later
pay_at_door_check_failed500AXYN could not read the event's current setting. Nothing was saved. Retry

Venue address

Every event needs a venue with a street and a city before it can go on sale. Guests use them to find the show, and AXYN uses them for maps and ticket emails. You can save a venue with only a name while you set things up, but publish will stop with 422 venue_address_incomplete until the address is in.

To add the missing address, send it once:

curl -sS -X PATCH "$AXYN_BASE_URL/v1/tenants/$TENANT_ID/venues/$VENUE_ID" \
  -H "x-api-key: $AXYN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address_line1": "1350 Third Street",
    "city": "Napa",
    "region": "CA",
    "postal_code": "94559",
    "country": "US",
    "timezone": "America/Los_Angeles"
  }'

The save must leave the street, the city and the time zone all set. The time zone decides how show times read for guests, so it is part of a complete place. This call only fills in parts that are empty. It never changes or removes a part the venue already has, because people may already hold tickets that show it. Leave out the parts you do not want to send. Sending a part again with the same value is fine. If the venue has no map location yet, AXYN looks one up from the address.

Once the venue has a street, a city and a time zone, the address is locked and this call stops working. A venue that has a street and a city but no time zone can still send just timezone.

The same rule holds after publish. While an event is on sale, paused or sold out, you cannot move it to a venue without a street and a city, or remove its venue. Resume checks the venue the same way publish does.

errorStatusWhen
venue_address_incomplete422Publish when the venue has no street or no city
venue_address_incomplete400The PATCH would still leave the street, the city or the time zone empty
venue_address_incomplete422Resume, or an event PATCH that moves a listed event to a venue with no street or city
venue_required422An event PATCH that sets venue_id to null on a listed event
venue_address_locked409The venue already has a street, a city and a time zone, or you tried to change a part it has
(message)400A field is not a string or null, or timezone is not a real time zone like America/Los_Angeles
(message)403Your API key belongs to a different tenant than the URL
venue_not_found404No active venue with that id in your tenant

Idempotency

POST /v1/orders and POST /v1/orders/{orderId}/payments/start require an Idempotency-Key header of 8 to 128 characters. A missing or bad key is 400.

Order create matches a key on the key alone (per buyer), not on the body. The body is still validated first, so an invalid body is refused as usual. After that, sending a key again returns the order it first created, even when the cart changed: a new cart under an old key does not create a new order and is not refused as a conflict. So generate a new key for every distinct cart, and reuse a key only to retry the same submit. A replay is refused when:

  • the order is over (expired, cancelled or failed): 409 hold_expired;
  • it is on the other payment rail (card vs cash_at_entry): 409 order_already_placed, 409 hold_expired, 409 idempotency_key_reused, 409 checkout_hold_payment_method_locked (seated hold) or 409 order_payment_in_flight (see the checkout table above);
  • the attendees you sent do not match the tickets the order holds: 400;
  • you sent displayed_total_cents and the order's total differs: 409 total_changed.

Payment start answers 409 idempotency_key_reused when the key already started another order.

Rate limits

On 429, the body is typically { "success": false, "error": "rate limit exceeded" }. Standard RateLimit-Limit / RateLimit-Remaining headers may be present — respect them and back off exponentially. Do not disable limits in your client for "dev convenience."

Checkout and token exchange limits count per client IP. If your server calls them for your buyers, attest each buyer's IP so they do not share your server's limit: Calling for your buyers from your server.

POST /v1/seats/hold has three limits. Each answers 429:

errorLimit
rate limit exceeded60 hold requests per buyer session per minute, and 120 per IP address per minute across events
seat_hold_limit_exceeded40 chairs held at once on one event from one IP address, across every session and hold_owner that IP uses

A chair stops counting toward the 40 as soon as its hold ends: released, expired, sold, or taken by another buyer after it lapsed. Re-holding a chair you already hold (to extend it) does not count it twice. Release chairs the buyer dropped instead of letting them expire. If your server holds seats for many buyers, attest each buyer's IP (link above), or all of them share one budget.

Common mistakes

  • Retrying non-idempotent writes without a key.
  • Treating scan result_code failures as 5xx.
  • Probing other tenants to map inventory (enumeration).
  • Assuming a structured code field exists when only error is in the contract.

Next