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

# Errores

> La forma de un error, cómo programar contra él y cómo encontrar un pedido.

Cuando algo sale mal, la API responde con el estado HTTP que corresponde y un cuerpo
`application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)):

```json theme={null}
{
  "type": "https://docs.craqui.com/errors/scope_required",
  "title": "La clave no tiene ese permiso",
  "status": 403,
  "code": "scope_required",
  "detail": "Crea una clave con el permiso que hace falta.",
  "request_id": "req_01hzx8m4k2a7d9q3f5w6y8z0bc",
  "doc_url": "https://docs.craqui.com/errors/scope_required",
  "required_scope": "sessions:read"
}
```

| Campo | Qué es |
| - | - |
| `type` | El link a la página de este error, con qué hacer. |
| `title` | Un resumen corto, para una persona. |
| `status` | El mismo estado HTTP de la respuesta. |
| `code` | El código estable del error. **Programa contra este campo.** |
| `detail` | Qué pasó y qué hacer, para una persona. |
| `request_id` | El id del pedido. También viene en el header `Request-Id`. |
| `doc_url` | Igual a `type`. |
| `required_scope` | Solo en `scope_required`: el permiso que le falta a la clave. |
| `errors` | Solo en `validation_failed`: un elemento por parámetro con problemas, con `field` y `code`. |

## Cómo programar contra un error

* Decide por `code`, nunca por `title` ni por `detail`: esos textos son para personas y pueden cambiar
  de redacción.
* La lista de códigos puede crecer. Trata un `code` que no conoces como un error genérico de su
  `status`.
* Reintenta solo lo que tiene sentido reintentar: `rate_limited` (después de `Retry-After`) e
  `internal_error`. Un `401` o un `403` no se arregla reintentando.
* Guarda el `request_id` en tus logs.

## Encontrar un pedido

Cada respuesta, también las exitosas, trae el header `Request-Id`. La propietaria del estudio ve cada
pedido de los últimos 30 días en su panel, en la actividad de la API, con su `request_id`, su estado y,
si falló, el error completo. Si nos escribes por un problema, manda el `request_id`.

## Todos los códigos

| Código | Estado HTTP | Qué significa |
| - | - | - |
| [`missing_api_key`](https://docs.craqui.com/errors/missing_api_key) | 401 | Falta la clave |
| [`invalid_api_key`](https://docs.craqui.com/errors/invalid_api_key) | 401 | La clave no es válida |
| [`revoked_api_key`](https://docs.craqui.com/errors/revoked_api_key) | 401 | La clave fue revocada |
| [`expired_api_key`](https://docs.craqui.com/errors/expired_api_key) | 401 | La clave venció |
| [`legacy_api_key`](https://docs.craqui.com/errors/legacy_api_key) | 401 | Esa es una clave del API anterior |
| [`api_key_suspended`](https://docs.craqui.com/errors/api_key_suspended) | 403 | La clave está en pausa |
| [`plan_required`](https://docs.craqui.com/errors/plan_required) | 403 | Tu plan no incluye la API |
| [`browser_not_allowed`](https://docs.craqui.com/errors/browser_not_allowed) | 403 | La API se usa desde un servidor |
| [`scope_required`](https://docs.craqui.com/errors/scope_required) | 403 | La clave no tiene ese permiso |
| [`wrong_vertical`](https://docs.craqui.com/errors/wrong_vertical) | 403 | Esa ruta no es para tu tipo de negocio |
| [`invalid_api_version`](https://docs.craqui.com/errors/invalid_api_version) | 400 | Esa versión de la API no existe |
| [`idempotency_key_required`](https://docs.craqui.com/errors/idempotency_key_required) | 400 | Falta Idempotency-Key |
| [`idempotency_key_reused`](https://docs.craqui.com/errors/idempotency_key_reused) | 422 | Idempotency-Key ya usada con otro pedido |
| [`idempotency_in_progress`](https://docs.craqui.com/errors/idempotency_in_progress) | 409 | El mismo pedido todavía se está procesando |
| [`validation_failed`](https://docs.craqui.com/errors/validation_failed) | 400 | Hay datos inválidos |
| [`invalid_cursor`](https://docs.craqui.com/errors/invalid_cursor) | 400 | El cursor no sirve para esta búsqueda |
| [`route_not_found`](https://docs.craqui.com/errors/route_not_found) | 404 | Esa ruta no existe |
| [`not_found`](https://docs.craqui.com/errors/not_found) | 404 | No existe |
| [`sandbox_unavailable`](https://docs.craqui.com/errors/sandbox_unavailable) | 409 | Tu estudio de prueba no está listo |
| [`sandbox_contact_not_allowed`](https://docs.craqui.com/errors/sandbox_contact_not_allowed) | 422 | Ese contacto no se admite en el estudio de prueba |
| [`sandbox_account_reserved`](https://docs.craqui.com/errors/sandbox_account_reserved) | 422 | Ese email está reservado |
| [`rate_limited`](https://docs.craqui.com/errors/rate_limited) | 429 | Demasiados pedidos seguidos |
| [`internal_error`](https://docs.craqui.com/errors/internal_error) | 500 | Falló algo de nuestro lado |


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