FOOTBALL API
Sign inRequest a key
The collectionDocumentationMembershipStatusSupport
Sign inRequest a key
Documentation / Guides

FOOTBALL API ERRORS

Errors

Every error has a fixed code, a message that says what to do, and a request id to quote to support.

THE SHAPE

An error answers with its HTTP status and error in place of data. Match on error.code, never on the message: codes are fixed for ever, messages may be reworded.

403GET /v1/competitions/la-liga/seasons/2026/table, on the complimentary key
{
  "error": {
    "code": "upgrade_required",
    "message": "Spain's La Liga is part of membership. Your complimentary key reads this season's Premier League; membership opens every league and competition back to 2015/16, and live scores.",
    "plan": "Membership",
    "upgrade_url": "https://footballapi.org/membership",
    "docs": "https://footballapi.org/documentation/errors"
  },
  "meta": {
    "request_id": "req_387c702692379d69"
  }
}
error.codestringOne of the codes below.
error.messagestringWhat happened and what to do, in a sentence.
error.planstringThe plan that would answer, when a plan would.
error.upgrade_urlstringWhere to get it, with the plan.
error.docsstringThis page.
meta.request_idstringQuote it to support and we can find the call.

EVERY CODE

400bad_requestA parameter is missing or not in the right form, or the key was sent in the address. The message names what to fix.
401unauthorizedNo key, a key we do not know, or one replaced more than 24 hours ago.
403upgrade_requiredThe call reaches past this season's Premier League on the complimentary key, or asks for live scores. The answer names membership and links to it.
404not_foundNo such endpoint, id or competition, or a season outside what the collection serves for that league.
422unknown_parameterA parameter this endpoint does not take. The message lists the ones it does.
429rate_limitedToo many calls this minute. Wait for Retry-After seconds.
429quota_exceededThe day's 50 calls are used, on the complimentary key. They come back at 00:00 UTC.
500server_errorSomething failed on our side. It is logged; try again shortly, and quote the request id if it persists.

WHEN TO RETRY

Retry rate_limited after Retry-After seconds, and server_error after a short pause. The others answer the same until the call changes, so fix the call instead.

PREVIOUSPaginationNEXTMatches and results