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
| Status | Meaning |
|---|---|
| 400 | Bad request or validation failure |
| 401 | Missing or invalid credential |
| 403 | Valid credential, wrong scope or role |
| 404 | Not found (also used for enumeration-safe cross-tenant misses) |
| 409 | Conflict (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. |
| 422 | Semantic / business validation failure |
| 429 | Rate limited; back off and retry |
| 5xx | Server 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.
error | Create | Preview | When |
|---|---|---|---|
capacity_unavailable | 409 | 409 | Quantity is above what is still sellable. This is also how a sold-out ticket type answers |
addon_sold_out | 409 | An add-on in the cart does not have enough left | |
event_not_published, sale_not_started, sale_ended | 400 | 422 | A 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 tier | 400 | 422 | A 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 limit | 400 | 422 | The cart is below or above a ticket type's per-order limit, or above an add-on's |
event_cancelled | 400 | 422 | A show in the cart was cancelled |
cross_production_lines | 400 | 422 ¹ | A type that cannot sell on this order's show (another series, or a pass that does not admit it) |
coupon_* | 400 | 400 | Coupon refused. See the list in Headless API |
below_minimum_charge | 400 | 400 | The 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_changed | 409 | You sent displayed_total_cents and the real total differs. The body carries the real total_cents | |
order_payment_in_flight | 409 | The buyer's earlier hold on this show is already paying | |
checkout_hold_release_pending | 503 | The 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_ready | 409 | The organizer's payment setup cannot take charges, on any payment method (pay at the door included). On create nothing is reserved | |
hold_expired | 409 | Payment 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_reused | 409 | Payment 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_placed | 409 | Order 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_locked | 409 | Order 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_limit | 422 | Pay at the door is off for this event, or its limit is reached | |
ach_unavailable | 400 | Bank payment is not on for this organizer | |
payment_attempts_exceeded | 429 | Too many declined cards in the last 60 minutes from this checkout session (5), this email (5) or this IP address (10) | |
order_create_attempts_exceeded | 429 | More than 10 order creates for this show from one purchaser email and IP address in 10 minutes | |
rate limit exceeded | 429 | 429 | Per 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_unavailable | 503 | 503 | AXYN could not load the fees for this sale. Retry later |
payout_check_unavailable | 503 | AXYN could not check the organizer's payouts. On create nothing is reserved. Retry later | |
event not found, event_not_found | 400 / 404 | 404 | No 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.
error | When |
|---|---|
seating_not_ready | Publish before POST .../seating:ready with { "ready": true } |
seating_inventory_required | Ready/publish with no seats (reserved) or no sections (section) |
seating_tiers_required | Reserved sellable seat has no ticket type |
layout_not_seated | Apply / save / seating-ready called on GA |
overwrite_confirm_required | House already saved; send confirm_overwrite: true |
house_empty | Apply with no venue house geometry |
venue_required | Seated 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.
error | HTTP | When |
|---|---|---|
pay_at_door_needs_stripe | 422 | The payment setup cannot take charges. blocker says why (connect_required, connect_incomplete, connect_missing_on_platform, …) |
payout_check_unavailable | 503 | AXYN could not check the payment setup with Stripe. Nothing was saved. Retry later |
pay_at_door_check_failed | 500 | AXYN 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.
error | Status | When |
|---|---|---|
venue_address_incomplete | 422 | Publish when the venue has no street or no city |
venue_address_incomplete | 400 | The PATCH would still leave the street, the city or the time zone empty |
venue_address_incomplete | 422 | Resume, or an event PATCH that moves a listed event to a venue with no street or city |
venue_required | 422 | An event PATCH that sets venue_id to null on a listed event |
venue_address_locked | 409 | The venue already has a street, a city and a time zone, or you tried to change a part it has |
| (message) | 400 | A field is not a string or null, or timezone is not a real time zone like America/Los_Angeles |
| (message) | 403 | Your API key belongs to a different tenant than the URL |
venue_not_found | 404 | No 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) or409 order_payment_in_flight(see the checkout table above); - the
attendeesyou sent do not match the tickets the order holds:400; - you sent
displayed_total_centsand 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:
error | Limit |
|---|---|
rate limit exceeded | 60 hold requests per buyer session per minute, and 120 per IP address per minute across events |
seat_hold_limit_exceeded | 40 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_codefailures as 5xx. - Probing other tenants to map inventory (enumeration).
- Assuming a structured
codefield exists when onlyerroris in the contract.