#Errors
Every error has the same JSON shape:
{
"error": "list_api_disabled",
"message": "API access is turned off for this list. Turn it on in the list settings."
}| Field | Meaning |
|---|---|
error | Stable machine code. Branch on this. |
message | Human text. May change; not always present. |
required | insufficient_scope only: the scope the operation needs. |
retry_after_seconds | partner_rate_limited, auth_unavailable and FEATURE_GATE_UNAVAILABLE (when present): seconds to wait, the same value as the Retry-After header. |
retryable | auth_unavailable and FEATURE_GATE_UNAVAILABLE (when present): always true. |
max_rows | too_many_rows only: the per-call row limit (500). |
reason | partner_lists_disabled only, when present: a short machine-readable reason. |
Branch on error, never on message or on the HTTP status alone.
#Error codes
| Status | error | Meaning | Retry? |
|---|---|---|---|
| 400 | invalid_page | page is not a whole number of 1 or more. | No |
| 400 | invalid_per_page | per_page is not a whole number of 1 or more. | No |
| 400 | invalid_venue_id | venue_id is not a whole number. | No |
| 400 | invalid_event_id | The event id (or concert_sku) is not valid. GET /events/{id}/locations takes plain digits only. | No |
| 400 | invalid_location_id | The ticket type id is not plain digits of 1 or more. | No |
| 400 | invalid_list_id | The list id is not a whole number of 1 or more. Send plain digits: other numeric forms, such as 1e1 or 0x10, may be read as a different list id. | No |
| 400 | invalid_key | key is missing, blank, too long, or does not fit the list's key column type. | No |
| 400 | rows_required | rows is missing or empty. | No |
| 401 | missing_api_key | No Authorization: Bearer header. Repeated from one IP address, answered 429 partner_rate_limited instead. | No |
| 401 | invalid_api_key | The key was checked and is unknown, revoked, expired or has the wrong prefix. Repeated from one IP address, answered 429 partner_rate_limited instead. | No |
| 403 | insufficient_scope | The key lacks the scope in required. | No |
| 403 | partner_api_disabled | API access is off for your account. | No |
| 403 | partner_lists_disabled | Custom Lists is not enabled for your account. | No |
| 403 | list_api_disabled | API Access is off in this list's settings. | No |
| 404 | event_not_found | No such event on your account, a test event, or sales have closed. | No |
| 404 | location_not_found | No such ticket type on your account, a ticket type that is not sold on its own, one of a test event, or one whose event's sales have closed. | No |
| 404 | list_not_found | No such list on your account, or it is archived. | No |
| 404 | row_not_found | No active row with that key. | No |
| 405 | method_not_allowed | The HTTP method is not supported on this path. On event and availability paths the key is checked first, so a call without a valid key gets 401 instead. | No |
| 409 | ambiguous_concert_sku | The concert_sku matches more than one event. Use the numeric id. | No |
| 409 | list_not_ready | The list has no valid columns yet. | No |
| 413 | too_many_rows | More than 500 rows in one call. | No — split the batch |
| 429 | partner_rate_limited | Too many requests from this key or from your IP address (see Rate Limits), or repeated requests with a missing or invalid key from one IP address. | Yes, after Retry-After |
| 500 | any | An unexpected error. The body may not follow the error shape. | Yes, with backoff and a small cap |
| 502 | upstream_error | BetterTickets could not load or save the data. | Yes, with backoff and a small cap |
| 502 | request_refused | Custom Lists: refused for an unlisted reason. Can also arrive with a 4xx status. | No — contact BetterTickets if it persists |
| 503 | auth_unavailable | BetterTickets could not check the key for a moment. The key was not judged invalid. | Yes, after Retry-After |
| 503 | FEATURE_GATE_UNAVAILABLE | BetterTickets could not confirm your account's settings for a moment. | Yes, after Retry-After |
#Retrying
error | Retry? | How |
|---|---|---|
partner_rate_limited (429) | Yes | Wait Retry-After seconds, then retry one request at a time. |
auth_unavailable (503) | Yes | Wait Retry-After seconds (5) between attempts; retrying faster gets 429 partner_rate_limited. |
FEATURE_GATE_UNAVAILABLE (503) | Yes | Wait Retry-After seconds. If the header is missing (Custom Lists calls can answer a bare { "error": "FEATURE_GATE_UNAVAILABLE" }), wait 5 seconds. |
upstream_error (502) | Yes | Exponential backoff with jitter and a small cap on attempts. |
Any 500 | Yes | Exponential backoff with a small cap on attempts. |
request_refused (502 or 4xx) | No | Do not retry the same request; contact BetterTickets if it persists. |
| Any other 4xx | No | Fix the request, the key or the account settings first. |
Cap the number of attempts for every retryable error. 401 invalid_api_key and 404 answers are not temporary: retrying the same request straight away gets the same answer.
POST /lists/{id}/rows is safe to repeat: sending the same rows again updates them to the same values and reports them as unchanged.