# 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."
}
```

| 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](https://docs.bettertickets.com/rate-limits.md)), 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`.
