> ## 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 Legal 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": "status must be one of TRACKING, NOT_TRACKING.",
    "param": "status",
    "details": {
      "issues": [{ "path": "status", "message": "status must be one of TRACKING, NOT_TRACKING." }]
    }
  }
}
```

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

Every response also carries an `X-Request-Id` header; include it when
reporting an issue. Error responses repeat the `code` in an
`X-Croma-Error-Code` header, so you can branch without parsing the body.

## Types and codes

| Status | `type`                  | `code`                         | Meaning                                                                                                                                                       |
| ------ | ----------------------- | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request_error` | `invalid_param`                | A query parameter or body field failed validation; see `param` / `details`. Unknown enum values, an unrecognized `city`, or an invalid export body land here. |
| `400`  | `invalid_request_error` | `callback_unavailable`         | [Export](/legal/exports) callback delivery is temporarily unavailable. Wait inline or poll the status URL instead.                                            |
| `401`  | `authentication_error`  | `invalid_api_key`              | Missing or invalid key. See [Authentication](/legal/authentication).                                                                                          |
| `401`  | `authentication_error`  | `personal_api_key_not_allowed` | A personal key was used; organization keys only.                                                                                                              |
| `404`  | `not_found_error`       | `not_found`                    | No process with that id or radicado in your organization.                                                                                                     |
| `404`  | `not_found_error`       | `job_not_found`                | No [export job](/legal/exports) with that id in your organization.                                                                                            |
| `404`  | `not_found_error`       | `endpoint_not_found`           | No API endpoint at that path. See the [API Reference](/legal/api-reference/overview).                                                                         |
| `405`  | `invalid_request_error` | `method_not_allowed`           | Wrong method. Read endpoints are `GET`; exports are `POST`. The `Allow` header names the right one.                                                           |
| `429`  | `rate_limit_error`      | `rate_limited`                 | Quota exceeded; see [Rate limits](/legal/rate-limits).                                                                                                        |
| `500`  | `api_error`             | `internal_error`               | Unexpected internal error. Retry, and contact support with the `X-Request-Id` if it persists.                                                                 |
| `502`  | `api_error`             | `job_failed`                   | An [export](/legal/exports) that was waited on inline failed.                                                                                                 |

<Note>
  A "no match" on a list is never a `404`: searches and feeds return `200`
  with an empty `data`, and a defendant with no cases returns an empty list.
  Only the single-case endpoints (`GET /v1/processes/{id}` and its
  `/actions`) return `404`, and only when the id or radicado isn't in your
  organization. A case that exists but belongs to another organization also
  reads as `404`.
</Note>

<Note>
  [Exports](/legal/exports) can also fail as a **job** rather than as an HTTP
  error: a polled or called-back job carries the same `error` object inside the
  envelope, with `code: "job_failed"`.
</Note>