BetterTicketsAPI Docs

#Errors

Every error has the same JSON shape:

JSON
{
  "error": "list_api_disabled",
  "message": "API access is turned off for this list. Turn it on in the list settings."
}
FieldMeaning
errorStable machine code. Branch on this.
messageHuman text. May change; not always present.
requiredinsufficient_scope only: the scope the operation needs.
retry_after_secondspartner_rate_limited, auth_unavailable and FEATURE_GATE_UNAVAILABLE (when present): seconds to wait, the same value as the Retry-After header.
retryableauth_unavailable and FEATURE_GATE_UNAVAILABLE (when present): always true.
max_rowstoo_many_rows only: the per-call row limit (500).
reasonpartner_lists_disabled only, when present: a short machine-readable reason.

Branch on error, never on message or on the HTTP status alone.

#Error codes

StatuserrorMeaningRetry?
400invalid_pagepage is not a whole number of 1 or more.No
400invalid_per_pageper_page is not a whole number of 1 or more.No
400invalid_venue_idvenue_id is not a whole number.No
400invalid_event_idThe event id (or concert_sku) is not valid. GET /events/{id}/locations takes plain digits only.No
400invalid_location_idThe ticket type id is not plain digits of 1 or more.No
400invalid_list_idThe 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
400invalid_keykey is missing, blank, too long, or does not fit the list's key column type.No
400rows_requiredrows is missing or empty.No
401missing_api_keyNo Authorization: Bearer header. Repeated from one IP address, answered 429 partner_rate_limited instead.No
401invalid_api_keyThe 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
403insufficient_scopeThe key lacks the scope in required.No
403partner_api_disabledAPI access is off for your account.No
403partner_lists_disabledCustom Lists is not enabled for your account.No
403list_api_disabledAPI Access is off in this list's settings.No
404event_not_foundNo such event on your account, a test event, or sales have closed.No
404location_not_foundNo 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
404list_not_foundNo such list on your account, or it is archived.No
404row_not_foundNo active row with that key.No
405method_not_allowedThe 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
409ambiguous_concert_skuThe concert_sku matches more than one event. Use the numeric id.No
409list_not_readyThe list has no valid columns yet.No
413too_many_rowsMore than 500 rows in one call.No — split the batch
429partner_rate_limitedToo 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
500anyAn unexpected error. The body may not follow the error shape.Yes, with backoff and a small cap
502upstream_errorBetterTickets could not load or save the data.Yes, with backoff and a small cap
502request_refusedCustom Lists: refused for an unlisted reason. Can also arrive with a 4xx status.No — contact BetterTickets if it persists
503auth_unavailableBetterTickets could not check the key for a moment. The key was not judged invalid.Yes, after Retry-After
503FEATURE_GATE_UNAVAILABLEBetterTickets could not confirm your account's settings for a moment.Yes, after Retry-After

#Retrying

errorRetry?How
partner_rate_limited (429)YesWait Retry-After seconds, then retry one request at a time.
auth_unavailable (503)YesWait Retry-After seconds (5) between attempts; retrying faster gets 429 partner_rate_limited.
FEATURE_GATE_UNAVAILABLE (503)YesWait 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)YesExponential backoff with jitter and a small cap on attempts.
Any 500YesExponential backoff with a small cap on attempts.
request_refused (502 or 4xx)NoDo not retry the same request; contact BetterTickets if it persists.
Any other 4xxNoFix 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.