Errors

The API uses standard HTTP status codes. Codes in the 200s mean success, the 400s mean something in the request needs fixing and the 500s mean a problem on our side.

Status codes

Each endpoint page lists the codes it returns — 200, 400, 401 and 429. As with any HTTP API, you may also see a 404 for a wrong path or a 5xx during an incident.

HTTP status codes
Code	Meaning	What to do
200 OK	The request succeeded.	Read the results from `data`.
400 Bad Request	A parameter is missing, has the wrong type or is out of range — for example a date not in YYYY-MM-DD.	Fix the request using the endpoint’s Parameters table. Don’t retry it unchanged.
401 Unauthorized	The API key is missing, mistyped or revoked.	Send a valid key in `x-api-key`. See Authentication.
404 Not Found	The path doesn’t exist — usually a typo or a missing version segment.	Check the path against the API reference.
429 Too Many Requests	You have reached your rate limit or monthly quota.	Wait for the limit to reset, then retry with backoff. See Rate Limits.
500 Internal Server Error	Something went wrong on our side.	Retry with backoff. If it persists, check API Status.
503 Service Unavailable	The API is temporarily unavailable, for example during maintenance.	Retry with backoff and check API Status.

Error response body

Errors return JSON with an error object holding the HTTP status and a human-readable message:

400 Bad Request · application/json

{
  "error": {
    "status": 400,
    "message": "Invalid parameter: date must be YYYY-MM-DD"
  }
}

Branch on the HTTP status code, not on the message. Messages are written for people and may be reworded.

Handling errors

Check the status before reading the body, and treat each group of codes differently:

const res = await fetch("https://api.gosportsapi.com/v1/football/fixtures?date=2026-09-26", {
  headers: { "x-api-key": process.env.GOSPORTS_API_KEY },
});
if (res.ok) {
  const { data, meta } = await res.json();
  // use data
} else if (res.status === 400 || res.status === 404) {
  // A problem with the request: log it, do not retry unchanged
  const { error } = await res.json();
  console.error(res.status, error.message);
} else if (res.status === 401) {
  // Missing, mistyped or revoked key
  throw new Error("Invalid API key");
} else if (res.status === 429 || res.status >= 500) {
  // Temporary: retry with backoff
}

Retrying safely

Retry only 429 and 5xx responses — they are temporary. 400, 401 and 404 fail the same way until you change the request.
Back off exponentially (1 s, 2 s, 4 s…) and add a little random jitter so many clients don’t retry in lockstep. There is a ready-made example in Rate Limits.
Cap the number of retries, then surface the error to your monitoring.
Every endpoint is a read-only GET, so a retry can never create duplicate data.
If errors persist, check API Status before digging into your own code.