Errors

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

An error answer has an error object in place of data. Branch on code, which never changes; message is for people.

{
  "error": {
    "code": "outside_plan_window",
    "message": "That date is outside what your plan reads (yesterday only).",
    "plan": "free",
    "request_id": "8c1f0a2b9d3e4f51",
    "docs": "https://horseracingapi.co.uk/documentation/errors"
  }
}

Code	Status	Means	What to do
`bad_request`	400	A value is the wrong shape: a date that is not YYYY-MM-DD, a cursor that is not ours, or a key sent in the address.	Fix the value the message names and send it again.
`unauthorized`	401	No key was sent, or the key is not one of ours.	Send your key in X-API-Key or as Authorization: Bearer. Copy it again from your account.
`upgrade_required`	403	Your plan does not reach this endpoint. The answer names the plans that do.	Choose a plan that has it on the pricing page; the same key reaches further at once.
`outside_plan_window`	403	The day asked for is outside what your plan reads. The answer gives your window and the day you asked for.	Ask for a day inside your window, or move to a plan that reads it.
`not_found`	404	No record has that id, or it is not British or Northern Irish racing.	Take ids from other answers; never build one.
`unknown_parameter`	422	A parameter this endpoint does not take. The answer lists the ones it does.	Remove it, or check its spelling against the list.
`rate_limited`	429	Too many calls this minute for your plan.	Wait for the seconds in Retry-After, then carry on at a steadier pace.
`quota_exceeded`	429	Your plan's calls for the month are used. The answer says when they reset.	Wait for the 1st (UTC), or move to a plan with more calls.
`server_error`	503	The data is not available just now.	Try again in a minute. It is logged and looked at.

A 403 is never temporary: retrying it only uses calls. An empty list is not an error; it is a 200 with meta.count 0. Quote request_id when you ask for help.

PreviousPagination NextCourses