Errors

Every error from the API has the same shape, whatever went wrong:

{
  "error": {
    "code": "not_found",
    "message": "Postcode ZZ9 9ZZ was not found."
  }
}

Use code in your program: it is stable. message is in plain words, for people, and may change.

A call that fails isn’t counted against your monthly quota. Only answers count.

Every code

Status	Code	What it means	What to do
401	`invalid_key`	No key, an unknown key, or a publishable key used with the API.	Send your secret key as `Authorization: Bearer ctf_sk_live_…`.
403	`key_revoked`	The key has been revoked.	Ask us for a new key.
404	`not_found`	No such field, postcode, place or endpoint.	Check the postcode, place name, `field_id` or path.
405	`method_not_allowed`	A method other than `GET`.	Use `GET`.
409	`ambiguous`	A place name matches more than one place, or none exactly.	Ask again with one of the `choices`, by name or by its point.
422	`outside_england`	The postcode or point is outside England, such as in Scotland or Wales.	We cover England only.
422	`bad_request`	The question can’t be answered as asked: two locations at once, none, a value out of bounds, or a blank or unreadable `q`.	Read `message`, which names the problem, and fix the request.
429	`quota_exceeded`	The month’s calls are used up.	Wait for `Retry-After` seconds (until the 1st, 00:00 UTC), or ask us for more.
429	`rate_limited`	More than 600 calls in a minute.	Wait for `Retry-After` seconds, then try again.
503	`too_slow`	The search took longer than 15 seconds and was stopped.	Try a smaller `radius_m`, or a postcode or point instead of a town.

See Quotas and limits for the limits behind 429 and 503.

Ambiguous places

When q is a place name that matches more than one place, the error lists the places we know by that name. Each choice has its name, its council and a point as [longitude, latitude]. The places in this example are illustrative.

{
  "error": {
    "code": "ambiguous",
    "message": "There is more than one Newport. Which one?",
    "choices": [
      { "name": "Newport (Isle of Wight)", "council": "Isle of Wight", "point": [-1.2931, 50.7008] },
      { "name": "Newport (Shropshire)", "council": "Telford and Wrekin", "point": [-2.3769, 52.7699] }
    ]
  }
}

If one place has the name with a qualifier, such as a single Newport (…), it is used without asking. If no place has the name exactly but some start with it, you get the same code with a message like “No place is called Testfrod. Did you mean one of these?”. To ask again, send the chosen name as q, or its point as lat and lng (the point’s second number is lat):

curl -H "Authorization: Bearer $CTF_KEY" \
  "https://api.checkthatfield.com/v1/scores?q=Newport%20(Shropshire)"

If you know the postcode, use it. A postcode never comes back ambiguous.

Example bodies

401 invalid_key

{ "error": { "code": "invalid_key", "message": "The API key is missing or not valid." } }

403 key_revoked

{ "error": { "code": "key_revoked", "message": "This API key has been revoked." } }

404 not_found

{ "error": { "code": "not_found", "message": "There is no field 999999." } }

405 method_not_allowed

{ "error": { "code": "method_not_allowed", "message": "That method isn't allowed here." } }

422 outside_england

{ "error": { "code": "outside_england", "message": "The location is outside England." } }

422 bad_request

{ "error": { "code": "bad_request", "message": "Give exactly one of postcode, q, or lat and lng." } }

429 quota_exceeded

HTTP/2 429
Retry-After: 1425600

{ "error": { "code": "quota_exceeded", "message": "This key has used its calls for the month." } }

429 rate_limited

HTTP/2 429
Retry-After: 23

{ "error": { "code": "rate_limited", "message": "Too many requests. Try again in a minute." } }

503 too_slow

{ "error": { "code": "too_slow", "message": "The search took too long. Try a smaller radius or a postcode." } }

Handling errors

Check the status

2xx is an answer. Anything else has an error body.

Branch on the code

Fix and resend bad_request, not_found and ambiguous. Wait and retry rate_limited. Stop on invalid_key, key_revoked and quota_exceeded, and tell someone.

Show the message if you must

message is written for people, so it is safe to log or show.

Partner API

Endpoints

Every code

Ambiguous places

Example bodies

Handling errors