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

# Errores

> El sobre de error y los códigos de estado de la API de Croma Legal.

## Sobre

Las respuestas exitosas devuelven `{ "data": … }`. Las fallas devuelven un
objeto `error` y un estado HTTP distinto de 2xx. Decide según el código de
estado, no según una bandera en el cuerpo:

```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." }]
    }
  }
}
```

| Campo     | Notas                                                                          |
| --------- | ------------------------------------------------------------------------------ |
| `type`    | Categoría amplia (ver abajo).                                                  |
| `code`    | Código específico legible por máquina. Decide según este.                      |
| `message` | Legible para humanos; seguro de mostrar en la interfaz.                        |
| `param`   | Campo que causó el error. Presente en errores de validación.                   |
| `details` | Detalle estructurado opcional (por ejemplo, todos los `issues` de validación). |

Cada respuesta trae además un encabezado `X-Request-Id`; inclúyelo al reportar
un problema. Las respuestas de error repiten el `code` en un encabezado
`X-Croma-Error-Code`, para que puedas decidir sin parsear el cuerpo.

## Tipos y códigos

| Estado | `type`                  | `code`                         | Significado                                                                                                                                                                                                     |
| ------ | ----------------------- | ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `invalid_request_error` | `invalid_param`                | Un parámetro de consulta o campo del cuerpo no pasó la validación; consulta `param` / `details`. Aquí caen los valores de enumerado desconocidos, una `city` no reconocida o un cuerpo de exportación inválido. |
| `400`  | `invalid_request_error` | `callback_unavailable`         | La entrega por callback de las [exportaciones](/es/legal/exports) no está disponible por ahora. Espera en línea o consulta la URL de estado.                                                                    |
| `401`  | `authentication_error`  | `invalid_api_key`              | Clave faltante o inválida. Consulta [Autenticación](/es/legal/authentication).                                                                                                                                  |
| `401`  | `authentication_error`  | `personal_api_key_not_allowed` | Se usó una clave personal; solo claves de organización.                                                                                                                                                         |
| `404`  | `not_found_error`       | `not_found`                    | No hay un proceso con ese id o radicado en tu organización.                                                                                                                                                     |
| `404`  | `not_found_error`       | `job_not_found`                | No hay un [trabajo de exportación](/es/legal/exports) con ese id en tu organización.                                                                                                                            |
| `404`  | `not_found_error`       | `endpoint_not_found`           | No hay un endpoint de la API en esa ruta. Consulta la [Referencia de API](/es/legal/api-reference/overview).                                                                                                    |
| `405`  | `invalid_request_error` | `method_not_allowed`           | Método incorrecto. Los endpoints de lectura son `GET`; las exportaciones son `POST`. El encabezado `Allow` indica el correcto.                                                                                  |
| `429`  | `rate_limit_error`      | `rate_limited`                 | Cuota excedida; consulta [Límites de tasa](/es/legal/rate-limits).                                                                                                                                              |
| `500`  | `api_error`             | `internal_error`               | Error interno inesperado. Reintenta y, si persiste, contacta a soporte con el `X-Request-Id`.                                                                                                                   |
| `502`  | `api_error`             | `job_failed`                   | Una [exportación](/es/legal/exports) esperada en línea falló.                                                                                                                                                   |

<Note>
  Una lista "sin coincidencias" nunca es un `404`: las búsquedas y los feeds
  devuelven `200` con `data` vacío, y un demandado sin procesos devuelve una
  lista vacía. Solo los endpoints de un proceso individual
  (`GET /v1/processes/{id}` y su `/actions`) devuelven `404`, y solo cuando el
  id o radicado no está en tu organización. Un proceso que existe pero
  pertenece a otra organización también se lee como `404`.
</Note>

<Note>
  Las [exportaciones](/es/legal/exports) también pueden fallar como **trabajo**
  en lugar de como error HTTP: un trabajo consultado por polling o recibido por
  callback trae el mismo objeto `error` dentro del sobre, con
  `code: "job_failed"`.
</Note>