Errors

A failed request answers with an HTTP status and one error object that says what went wrong, which parameter, and what to do.

The error object

422 response
{
  "error": {
    "type": "invalid_request_error",
    "code": "unavailable",
    "message": "Ticket type 9001 is not on sale for this event.",
    "param": "items[0].ticket_type_id",
    "request_id": "req_6f1c2a9e4b7d3f8a0c5e2b1d",
    "doc_url": "https://aveoevents.com/eos/api/documents/errors#unavailable"
  }
}
FieldMeaning
typeOne of the six types below. Branch on it for broad handling.
codeThe exact reason, from the list below. Branch on it for specific handling.
messageA sentence for people. It may be reworded, so do not match on it.
paramThe parameter at fault, such as items[0].quantity, or null.
request_idThe request’s id, also in the X-Request-Id header. Quote it when you ask AVEO for help.
doc_urlThis page, at the code’s entry.

Types and statuses

TypeStatusWhen
invalid_request_error400, 404, 409, 422Something in the request is wrong: a missing or bad parameter, an unknown id, or a state the action does not allow.
authentication_error401No key, a key that does not exist, or one that has expired or been revoked.
permission_error403The key is fine but lacks the permission, or the address or web page it was used from is not allowed.
idempotency_error409An Idempotency-Key was reused with a different request.
rate_limit_error429Too many requests for this key in the last minute. Wait for the time in Retry-After.
api_error500, 502Something went wrong on our side or in the ticket engine. Safe to retry with the same Idempotency-Key.

Retry only what can change by itself: 429 after Retry-After, and 5xx with the same Idempotency-Key. A 4xx answer will be the same until the request or the data changes.

The request

invalid_request_error. Something in the request is wrong: a missing or bad parameter, an unknown id, or a state the action does not allow.

parameter_missing
400
A required parameter is missing. param names it.
parameter_invalid
400
A parameter has the wrong type or form. param names it and message says what is expected.
invalid_json
400
The body is not a JSON object.
body_too_large
400
The body is over 64 KB.
invalid_limit
400
limit must be a whole number from 1 to 100.
invalid_cursor
400
The cursor is not one this API gave you.
invalid_idempotency_key
400
Idempotency-Key must be 1 to 255 characters.
not_found
404
There is no such object in this company.
unknown_endpoint
404
There is no such endpoint. Check the method and the path against the reference.
session_expired
409
The checkout session's hold has ended. Create a new session.
session_complete
409
The session's order is already placed. To undo it, cancel the order.
already_paid
409
The order is already paid.
order_cancelled
409
The order was cancelled.
event_cancelled
409
A cancelled event cannot be put on sale.
code_exists
409
The discount code already exists on one of the events.
not_scannable
409
The event has no door list yet. Set one up in EOS.
not_on_sale
422
The event's tickets are not on sale, or the company is not taking orders.
unavailable
422
A ticket type is sold out or off sale, or the quantity is outside its limits.
discount_invalid
422
The discount code does not work on this event.
payments_off
422
The company cannot take that kind of payment right now.
date_of_birth_required
422
A ticket type has an age limit, so that guest's date_of_birth is needed.
age_restricted
422
A guest is outside the ticket type's age limit on the day of the event.
not_refundable
422
There is no card payment to refund, or the amount is more than was paid.
unknown_event
422
One of event_ids is not an upcoming event with tickets.
no_events
422
There are no upcoming events with tickets to put the code on.
not_created
422
The discount code could not be created on any of the events.
plan_limit
422
The company's plan has no room for this: another webhook endpoint (Starter has none), or another device scanning at the same time (a door app counts as one for each key). message says the limit: move up a plan, or ask AVEO.
too_many_endpoints
422
A company can have up to 100 API webhook endpoints.
rejected
422
The ticket engine refused the request. message says why.

The key

authentication_error. No key, a key that does not exist, or one that has expired or been revoked.

missing_key
401
No key was sent. Send it as Authorization: Bearer followed by the key.
key_malformed
401
What was sent is not an AVEO EOS API key.
key_unknown
401
There is no such key. Check that all of it was copied.
key_revoked
401
The key was revoked. Make a new one on the API keys page.
key_expired
401
The key has expired. Make a new one on the API keys page.
key_wrong_company
401
The key belongs to another company.

What the key may do

permission_error. The key is fine but lacks the permission, or the address or web page it was used from is not allowed.

company_not_active
403
The company's AVEO EOS account is not active.
missing_scope
403
The key does not have the permission this needs. param names the permission.
plan_scope
403
The company's AVEO EOS plan does not include this permission, whatever the key holds. param names it; a bigger plan opens it.
publishable_key
403
A publishable key cannot do this. Call it from your server with a secret key.
secret_key_in_browser
403
A secret key was sent from a web page (the request had an Origin header). Use a publishable key in web pages.
origin_not_allowed
403
The web page's address is not one of this publishable key's web addresses.
ip_not_allowed
403
The request came from an IP address the key is not allowed from.

Idempotency

idempotency_error. An Idempotency-Key was reused with a different request.

idempotency_key_reused
409
The Idempotency-Key was used before with a different request.
request_in_progress
409
A request with the same Idempotency-Key is still running. Retry shortly.

Rate limit

rate_limit_error. Too many requests for this key in the last minute. Wait for the time in Retry-After.

rate_limited
429
Too many requests for this key in the last minute. Wait for the seconds in Retry-After.
too_many_failures
429
Too many requests from this address failed the key check in the last minute. Wait a minute and check the key.
too_many_holds
429
This visitor already holds as many checkout sessions as a publishable key allows. Complete or cancel one first.

On our side

api_error. Something went wrong on our side or in the ticket engine. Safe to retry with the same Idempotency-Key.

internal
500
Something went wrong on our side. It is logged, and retrying with the same Idempotency-Key is safe.
engine_unavailable
502
The ticket engine did not answer. Retry in a moment.