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

# Errors

> Every error has the same shape. Branch on the code, never on the message.

Every error comes back in this shape:

```json theme={null}
{
  "error": {
    "code": "insufficient_scope",
    "message": "This API key does not have the \"events:read\" scope. A group admin can add it in Settings → Integrations → API keys."
  }
}
```

**Branch on `code`.** The `message` is written for people. We may change its wording at any time.

## Codes

| Status | `code`               | What it means                                                                                                                        | What to do                                                                                      |
| ------ | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
| 400    | `invalid_request`    | A query parameter or cursor is wrong: a typo, an unknown parameter or a value out of range.                                          | Check the parameter against the [API reference](/api-reference/introduction).                   |
| 401    | `invalid_api_key`    | No key, or a key that is unknown, revoked or expired. It also happens when the admin who created the key is no longer a group admin. | Check the key. See [When a key stops working](/guides/authentication#when-a-key-stops-working). |
| 403    | `insufficient_scope` | The key does not have the scope this endpoint needs.                                                                                 | Add the scope to the key in Scoutworks.                                                         |
| 404    | `not_found`          | No such record in your group.                                                                                                        | Check the ID. IDs from another group are never found.                                           |
| 429    | `rate_limited`       | Too many requests.                                                                                                                   | Wait `retryAfter` seconds, then try again. See [Rate limits](/guides/rate-limits).              |
| 500    | `internal_error`     | Something went wrong on our side.                                                                                                    | Try again later. If it keeps happening, send us the `errorRef`.                                 |

## Extra fields

Some errors carry more:

* **`retryAfter`** on a `429`: the number of seconds to wait.
* **`errorRef`** on a `500`: a short reference. Quote it when you [contact us](https://scoutworks.app/contact), and we can find the exact request.

New codes may appear in future. Treat a code you do not know as a general failure.