Errors

Every error code, what it means and what to do about it.

One shape for every error

{
  "error": {
    "code": "quota_exceeded",
    "message": "This key has used its 100 calls for today. The allowance resets at 2026-10-03T00:00:00Z.",
    "resets_at": "2026-10-03T00:00:00Z",
    "docs": "https://basketballapi.net/documentation/errors"
  }
}

Switch on code: codes never change. message is a plain sentence you can show as it is, and may be reworded.

The codes

HTTP	Code	What to do
400	`bad_request`	A value is wrong, such as a date that is not a date. The message names it.
401	`unauthorized`	No key, or a key that is not valid or was revoked. Check the header.
403	`upgrade_required`	The endpoint or the date is on another plan. The answer names it in `plan`, with a link in `pricing`.
404	`not_found`	No record with that id, or no such endpoint.
422	`unknown_parameter`	A parameter this endpoint does not take. The message lists the ones it does.
429	`rate_limited`	Too many calls this minute. Wait the seconds in `Retry-After`.
429	`quota_exceeded`	Today's calls are used up. Try again after `resets_at`, or move to a bigger plan.
500	`server_error`	Something went wrong on our side. It is logged; try again shortly.

Retrying

Retry a 429 after Retry-After and a 500 after a short wait. Never retry a 400, 401, 403, 404 or 422 unchanged: the same request fails the same way.