Errores - API de Craqui

Cuando algo sale mal, la API responde con el estado HTTP que corresponde y un cuerpo application/problem+json (RFC 9457):

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