Errors and status codes

Last updated 2026-10-30

Errors return JSON with a human-readable detail field that names the problem, for example the parameter that failed or the plan you need. Successful responses return 200 with "success": true.

Status codes

Status	Meaning	What to do
400	A parameter value is invalid, for example an unknown bookmaker key or an unsupported option. The message lists what was wrong.	Correct the parameter named in the message.
401	API key missing or not recognized.	Send the key in the `x-api-key` header.
403	The endpoint, sport or market is not on your plan. The message names the plan required.	Upgrade, or call something your plan includes.
404	Sport or resource not found, or not available on your plan.	Check the key with `GET /sports/`.
422	The request failed validation. The body pinpoints the parameter.	Fix the parameter type or format.
429	Daily quota reached, or a temporary block after repeated failed authentication.	Wait for `Retry-After`. See rate limits.

Error body

{"detail":"Daily rate limit reached (25 requests/day). Resets at midnight UTC."}

Empty results are not errors

A 200 with an empty data array usually means the league has no upcoming games right now, for example between seasons. Check GET /sports/ for what is currently available, or query a different league.

Handling errors in code

import time
import requests

def get_json(path, api_key, params=None, attempts=3):
    """GET with handling for 429 (quota or temporary block) and network errors."""
    for attempt in range(attempts):
        try:
            r = requests.get(f"https://api.bettingdataapi.com{path}", headers={"x-api-key": api_key},
                             params=params or {}, timeout=10)
        except requests.RequestException:
            time.sleep(2 ** attempt)
            continue
        if r.status_code == 429:
            wait = int(r.headers.get("Retry-After", "60"))
            # A daily-quota 429 can mean hours until 00:00 UTC. Do not spin.
            raise RuntimeError(f"Rate limited; retry after {wait} s: {r.json().get('detail')}")
        if r.status_code >= 400:
            raise RuntimeError(f"HTTP {r.status_code}: {r.json().get('detail')}")
        print("remaining today:", r.headers.get("X-RateLimit-Remaining"))
        return r.json()
    raise RuntimeError("network error after retries")

More examples: Python, JavaScript.

Try it with a free key

25 requests per day, NFL, NBA and MLB moneylines, no credit card.

Get a free API key