Errors
On this page
How the Manage Bet Codes error envelope works
Every Manage Bet Codes API error returns one JSON envelope with code, message, docs, request_id, and details. Every response carries X-Request-ID matching the error request_id: give that ID to support when reporting a problem.
{
"error": {
"code": "api_quota_exhausted",
"message": "Monthly API credits are finished. Upgrade or wait for the reset.",
"docs": "https://managebetcodes.app/docs/errors",
"request_id": "req_...",
"details": {"used": 5000, "limit": 5000, "resets_at": "2026-12-01T00:00:00Z"}
}
}Which error code means what and when it fires
The Manage Bet Codes API returns one code per failure across auth, quota, validation, booking, and transport faults: 401 invalid_key for bad keys, 403 plan_required when an action requires an API plan, 404 codes for missing rows, 409 codes for conflicts, 422 codes for bad input, 429 codes for exhausted quotas with a Retry-After header, and 502, 503, or 504 for downstream failures.
| HTTP | Code | When |
|---|---|---|
| 400 | invalid_request | Malformed body. |
| 401 | invalid_key | Missing, unknown, revoked, or rotated key. |
| 403 | account_blocked | The account is banned. |
| 403 | plan_required | The action requires an API plan (such as async jobs) or a missing entitlement. |
| 403 | email_unverified | Verify your email first. |
| 404 | not_found | No route matches that path. |
| 405 | method_not_allowed | That method is not allowed here. |
| 404 | slip_not_found | No slip for the code. |
| 404 | track_not_found | No track for this key owner. |
| 404 | job_not_found | No job for this key owner. |
| 404 | history_not_found | No history row for this key owner. |
| 404 | book_not_found | No book row for this key owner. |
| 404 | event_not_found | No event for this ID. |
| 404 | market_not_found | No market for this ID. |
| 404 | plan_not_found | No discovery plan for this key. |
| 404 | webhook_not_found | No webhook for this key owner. |
| 409 | idempotency_conflict | Same key and idempotency key, different body. |
| 409 | track_already_exists | This code is already tracked. |
| 409 | cancel_conflict | This subscription cannot be cancelled here. |
| 409 | job_not_cancellable | The job is already done. |
| 409 | key_limit_reached | The plan's key limit is reached. |
| 409 | plan_expired | The discovery plan is older than 10 minutes. |
| 409 | plan_used | The plan was already consumed. |
| 422 | unsupported_bookmaker | Unknown alias. details.hint gives a hint. |
| 422 | invalid_code | The code shape does not match the bookmaker. |
| 422 | conversion_failed | The converter returned an error. |
| 422 | conversion_disabled | Policy block (blocked: true). |
| 422 | invalid_split_count | The count is outside 2 to 20. |
| 422 | invalid_merge | Fewer than 2 pairs, or more than 30. |
| 422 | too_many_targets | More than 6 synchronous targets. |
| 422 | too_many_codes | More than 20 codes in a job. |
| 422 | too_many_picks | More than 50 picks. |
| 422 | too_many_queries | More than 20 queries. |
| 422 | no_targets | The target list is empty. |
| 422 | games_not_bookable | A strict book has unresolved picks. |
| 422 | odds_changed | The price moved beyond the tolerance. |
| 422 | book_unsupported | The bookmaker cannot create a code. |
| 422 | book_failed | The bookmaker refused the code. |
| 429 | api_quota_exhausted | API plan credits are empty. |
| 429 | plan_quota_exhausted | Regular plan daily credits are empty. |
| 429 | search_quota_exhausted | The daily search cap is reached. |
| 429 | rate_limited | The per-key request rate is reached. |
| 502 | bookmaker_unavailable | The source fetch failed at transport level. |
| 502 | payment_unavailable | The payment provider did not answer. |
| 503 | renderer_unavailable | The image renderer is down. |
| 504 | timeout | The action exceeded its budget. |
| 500 | internal_error | Unhandled error. |
How to retry a failed call and recover quota
Retry a Manage Bet Codes 429 after the Retry-After delay, and retry 502, 503, and 504 with backoff: the Python and TypeScript SDKs honor Retry-After automatically. Use limits to check plan and rate caps and charge-order to see which credit pool pays.