Errors

One JSON shape, a stable business code, and a clear rule about what is worth retrying.

Error shape

Errors use a JSON detail field carrying a business code:

{"detail": "competition_not_selected"}

Never log or echo the API key when handling an error.

Code	Status	Meaning
`invalid_match_id`	400	Malformed ID, or a `fixture:*` identifier.
`invalid_bulk_request`	400	Malformed bulk body.
`bulk_limit_exceeded`	400	More than 100 IDs requested.
`duplicate_match_ids`	400	The bulk list contains duplicates.
`competition_not_selected`	403	Known competition, not in your selection.
`bulk_not_available`	403	Bulk is not enabled for this plan.
`competition_not_found`	404	Unknown catalog code.
`match_not_found`	404	Unknown match, or outside your selection.
`rate_limit_exceeded`	429	Minute request limit reached.
`concurrency_limit_exceeded`	429	Too many requests in flight.

Do not retry 400, 401, 403, or 404 — the request will fail identically.
Retry with care on 429, honoring Retry-After. Remember that an admitted request already consumed a unit.
Retry network errors and 5xx with bounded backoff.