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

# Errors

> The Croma API error envelope and status codes.

## Envelope

Successful responses return `{ "data": … }`. Failures return an `error` object
and a non-2xx HTTP status. Branch on the status code, not a body flag:

```json theme={"dark"}
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_param",
    "message": "String must contain at least 3 character(s)",
    "param": "name",
    "details": { "issues": [{ "path": "name", "message": "String must contain at least 3 character(s)" }] }
  }
}
```

| Field     | Notes                                                      |
| --------- | ---------------------------------------------------------- |
| `type`    | Broad category (see below).                                |
| `code`    | Specific machine-readable code. Branch on this.            |
| `message` | Human-readable; safe to surface in UI.                     |
| `param`   | Offending field. Present on validation errors.             |
| `details` | Optional structured detail (e.g. all validation `issues`). |

## Types and codes

| Status | `type`                  | `code`                         | Meaning                                                                         |
| ------ | ----------------------- | ------------------------------ | ------------------------------------------------------------------------------- |
| `400`  | `invalid_request_error` | `invalid_param`                | Body failed validation; see `param` / `details`.                                |
| `400`  | `invalid_request_error` | `too_many_results`             | Query matched too many records to return. Narrow it.                            |
| `401`  | `authentication_error`  | `invalid_api_key`              | Missing or invalid key.                                                         |
| `401`  | `authentication_error`  | `personal_api_key_not_allowed` | A personal key was used; org keys only.                                         |
| `404`  | `not_found_error`       | `endpoint_not_found`           | No API endpoint at that path. See the [API Reference](/api-reference/overview). |
| `405`  | `invalid_request_error` | `method_not_allowed`           | Wrong method. Data endpoints are `POST`.                                        |
| `429`  | `rate_limit_error`      | `rate_limited`                 | Quota exceeded; see [Rate limits](/rate-limits).                                |
| `5xx`  | `upstream_error`        | `<source>_upstream`            | A government source failed or was unreachable.                                  |
| `500`  | `api_error`             | `internal_error`               | Unexpected internal error.                                                      |

<Note>
  Not every endpoint emits every code; each endpoint's reference page lists its
  own. A "no match" is never a `404`; it's a successful `200`. Registraduría,
  SUNAT, and RREE return `found: false`, and SICAAC and Superfinanciera return
  an empty list. A `404` means the endpoint or job id itself doesn't exist.
</Note>

<Note>
  [Async lookups](/async-jobs) can fail as a **job** rather than an HTTP error. A
  failed job carries the same `error` object in the envelope, with
  `code: "job_failed"`.
</Note>