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

# Errors

> How the API reports failures.

Kua uses conventional HTTP status codes and a consistent JSON error body.

## Error shape

```json theme={null}
{
  "code": "INSUFFICIENT_SCOPE",
  "message": "This API key is missing the 'payroll:write' scope."
}
```

* `code` — a stable, machine-readable identifier you can branch on.
* `message` — a human-readable explanation (may change; don't parse it).

## Status codes

| Status                | Meaning                                                                                          |
| --------------------- | ------------------------------------------------------------------------------------------------ |
| `200` / `201` / `202` | Success.                                                                                         |
| `204`                 | Success, no content.                                                                             |
| `400`                 | Malformed request or a validation error (see `code`).                                            |
| `401`                 | Missing or invalid API key.                                                                      |
| `403`                 | The key is valid but lacks the required scope (`INSUFFICIENT_SCOPE`).                            |
| `404`                 | The resource doesn't exist (or isn't yours).                                                     |
| `409`                 | Conflict — e.g. an `Idempotency-Key` reused with a different body.                               |
| `5xx`                 | Something went wrong on Kua's side. Safe to retry with the same [idempotency key](/idempotency). |

## Common codes

| Code                    | When                                                                                                                                                |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `INSUFFICIENT_SCOPE`    | The API key is missing a required scope.                                                                                                            |
| `MODULE_NOT_ENABLED`    | The endpoint belongs to an add-on the company hasn't enabled. The body includes the `module`; a company admin enables it in **Settings → Modules**. |
| `TEST_MODE_UNSUPPORTED` | A write to an add-on endpoint was attempted with a `kua_test_` key. Add-ons have no sandbox yet — use a live key.                                   |
| `WEBHOOK_INVALID_URL`   | A webhook endpoint URL wasn't a valid absolute URL.                                                                                                 |

<Note>
  Every request is scoped to the company that owns the API key. Asking for another
  company's data returns `404`, never that data.
</Note>