Errors

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

Every error is one shape, with a code that never changes and a message written for people:

JSON

{
  "error": {
    "code": "upgrade_required",
    "message": "The free key reads yesterday only. Today and the week ahead are on Live.",
    "plan": "live",
    "docs": "https://tvschedule.org/documentation/errors#upgrade_required"
  }
}

Write your code against code; show message to people. An empty result is never an error: it is a 200 with meta.count 0.

Code	HTTP	What it means	What to do
`bad_request`	400	A value is the wrong shape: a date that is not YYYY-MM-DD, a two-character search, a key sent in the address.	Fix the value the message names and send it again.
`unauthorized`	401	No key was sent, or it is not an active TV Schedule key.	Send it as Authorization: Bearer <key> or X-API-Key. Your keys are in your account.
`upgrade_required`	403	Your plan does not read this: a day outside its window, or an endpoint on Live and Complete.	The message names the plan that does. Upgrade on the same key at /pricing.
`not_found`	404	Nothing has that id, or there is no endpoint at that address.	Take ids from the search and directory endpoints. Every address is listed in these docs.
`unknown_parameter`	422	A query parameter this endpoint does not take.	The message lists the ones it does take.
`rate_limited`	429	Faster than your plan's pace per minute.	Wait for Retry-After seconds. The X-RateLimit headers show where you are.
`quota_exceeded`	429	Your plan's allowance for the day or month is used.	It resets at the time in the message, or upgrade for a bigger allowance.
`server_error`	500	Something went wrong on our side, or the data was out of reach for a moment.	Try again in a minute. It has been logged, and /status shows the state of the service.

PreviousPagination NextMCP server