Skip to main content

Errors & status codes

Errors & status codes

When a request fails, look at the HTTP status code. This page tells you what it means and what to do next.

Credits

Only successful requests (status 200) consume credits and return the credit headers.

Quick cheat sheet

  • 400 → your URL/inputs are wrong
  • 401 / 403 → your apiKey is missing / invalid / inactive
  • 402 → you ran out of credits
  • 404 → wrong endpoint or unknown fixtureId
  • 429 → too many requests (slow down + cache + backoff)
  • 5xx → server-side issue (retry + check status page)

200 — OK (success)

Request worked.

Tip

Every successful request returns these headers:

  • x-credits-cost: credit cost of this request
  • x-credits-used: credits used since the last reset
  • x-credits-remaining: credits remaining until the next reset

400 — Bad Request (your inputs are wrong)

Typical causes:

  • missing required parameters (like apiKey)
  • invalid fixtureId format (must be UUID)
  • invalid groups value (typo or unsupported group)
  • invalid history date format (must be ISO 8601)

Fix:

  • compare your URL with the docs
  • ensure history timestamps end with Z (Zulu = UTC)
    example: 2025-04-24T16:00:00Z

401 — Unauthorized (missing/invalid apiKey)

Typical causes:

  • no apiKey in the URL
  • typo in the key

Fix:

  • copy the key again from your dashboard
  • replace YOUR_API_KEY in the URL

403 — Forbidden (key is not allowed)

Typical causes:

  • subscription ended / key inactive
  • plan does not include that feature

Fix:

  • check your subscription status in the dashboard

402 — Insufficient credits (no credits left)

Meaning:

  • your plan has not enough credits remaining for the current request in that subscription period

Consider upgrading to a higher-tier plan.


404 — Not Found (doesn’t exist)

Typical causes:

  • endpoint path typo
  • unknown fixtureId
  • fixture not available (outside the 17-day forecast window)

Fix:

  • call /fixtures again and use a valid fixtureId
  • double-check the route spelling

429 — Too Many Requests (slow down)

Meaning:

  • you are hitting rate limits / sending requests too fast

Fix:

  • add a small waiting time between making requests.
  • retry with exponential backoff:
    • wait 8s → 16s → 32s → 64s (then stop or slow down more)

500 / 502 / 503 — Server error (our side)

Meaning:

  • temporary problem on the API side

Fix:

  • retry with backoff
  • check the operational status page: https://lineupapi.instatus.com/
  • if it continues, contact support with:
    • time (UTC),
    • endpoint you called (remove your apiKey),
    • and any request-id header (if present)