> ## 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: how failures are shaped, every status code the API returns, stable error codes and how to branch on them safely in a client.

## 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`). |

Responses from data endpoints also carry an `X-Request-Id` header; include it
when reporting an issue.

## 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` | The key has no organization behind it. |
| `404` | `not_found_error` | `endpoint_not_found` | No API endpoint at that path. See the [API Reference](/api-reference/overview). |
| `404` | `not_found_error` | `job_not_found` | No [async job](/async-jobs) with that id in your organization. |
| `410` | `not_found_error` | `endpoint_retired` | The endpoint passed its sunset date. The `Link` header names its successor; see [Versioning](/versioning#deprecation). |
| `405` | `invalid_request_error` | `method_not_allowed` | Wrong method. Data endpoints are `POST`. |
| `402` | `billing_error` | `plan_limit_reached` | The plan's credits for this period are spent; see [Rate limits](/rate-limits#credits). |
| `429` | `rate_limit_error` | `rate_limited` | Hourly ceiling 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`: single-record
  lookups return `found: false`, and searches 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>


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