> ## Documentation Index
> Fetch the complete documentation index at: https://docs.checkthatfield.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Every error the API returns, what it means, and what to do.

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

```json theme={null}
{
  "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.

> [!NOTE]
>
> 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](https://docs.checkthatfield.com/api/quotas-and-limits.md) 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.

```json theme={null}
{
  "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`):

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

> [!TIP]
>
> If you know the postcode, use it. A postcode never comes back ambiguous.

## Example bodies

> [accordion] 401 invalid\_key
>
> ```json theme={null}
> { "error": { "code": "invalid_key", "message": "The API key is missing or not valid." } }
> ```

> [accordion] 403 key\_revoked
>
> ```json theme={null}
> { "error": { "code": "key_revoked", "message": "This API key has been revoked." } }
> ```

> [accordion] 404 not\_found
>
> ```json theme={null}
> { "error": { "code": "not_found", "message": "There is no field 999999." } }
> ```

> [accordion] 405 method\_not\_allowed
>
> ```json theme={null}
> { "error": { "code": "method_not_allowed", "message": "That method isn't allowed here." } }
> ```

> [accordion] 422 outside\_england
>
> ```json theme={null}
> { "error": { "code": "outside_england", "message": "The location is outside England." } }
> ```

> [accordion] 422 bad\_request
>
> ```json theme={null}
> { "error": { "code": "bad_request", "message": "Give exactly one of postcode, q, or lat and lng." } }
> ```

> [accordion] 429 quota\_exceeded
>
> ```http theme={null}
> HTTP/2 429
> Retry-After: 1425600
> ```
>
> ```json theme={null}
> { "error": { "code": "quota_exceeded", "message": "This key has used its calls for the month." } }
> ```

> [accordion] 429 rate\_limited
>
> ```http theme={null}
> HTTP/2 429
> Retry-After: 23
> ```
>
> ```json theme={null}
> { "error": { "code": "rate_limited", "message": "Too many requests. Try again in a minute." } }
> ```

> [accordion] 503 too\_slow
>
> ```json theme={null}
> { "error": { "code": "too_slow", "message": "The search took too long. Try a smaller radius or a postcode." } }
> ```

## Handling errors

**1. Check the status**

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

**2. 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.

**3. Show the message if you must**

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.