Errores y límites

El contrato de errores es estable: códigos fijos, un formato único y una señal explícita de si conviene reintentar.

El formato

Todo error responde el mismo body:

{
  "code": "UNAUTHORIZED",
  "message": "missing bearer token",
  "request_id": "fafc24a5-6e77-4324-bd84-0f5a3a3deef7",
  "retryable": false
}

(Respuesta real de un request sin token.) Programe contra code, que es contractual; message es descriptivo y puede mejorar con el tiempo. retryable indica si el mismo request puede tener éxito al reintentarse sin cambiar nada (true solo en RATE_LIMITED e INTERNAL).

Los códigos

`code`	HTTP	cuándo ocurre
`INVALID_PARAMS`	400	Parámetro faltante o mal formado, `from > to`, rango mayor a 5 años, `as_of_revision` fuera de rango, o `page_token` corrupto o de otra consulta.
`UNAUTHORIZED`	401	Token ausente, inválido, revocado o expirado. El servicio nunca repite el token en la respuesta.
`UNSUPPORTED_CURRENCY`	404	Moneda que la API sabe que no sirve. Ejemplo real: `currency=EUR` responde `{"code": "UNSUPPORTED_CURRENCY", "message": "currency 'EUR' is not served by this API", …}`.
`UNSUPPORTED_SERIES`	404	Serie distinta de `publicado` y `cierre`.
`NO_OBSERVATIONS`	404	Consulta válida pero sin observaciones: rango sin datos, serie aún sin cobertura, o `at` anterior a la primera revisión en `/v1/revisions`. Distinto por diseño de `UNSUPPORTED_CURRENCY`: "no hay datos" no es "no sirvo esa moneda".
`NOT_FOUND`	404	Observación o evidencia inexistente para el UUID pedido.
`RATE_LIMITED`	429	Límite del token excedido. Trae encabezado `Retry-After` con los segundos a esperar.
`INTERNAL`	500	Error interno. El detalle queda en los registros del servicio (referenciable por `request_id`), nunca en el body.

Límites de uso

60 requests por minuto y 5 000 por día por token.
Ante 429, espere lo que indique Retry-After. Si su consumo legítimo excede estos límites, escriba a soporte@eurekia.pe.

Paginación a revisión fija

/v1/rates devuelve máximo 366 ítems por página. Si hay más, viene next_page_token: un token opaco que lleva embebida la revisión de la primera página y la consulta a la que pertenece.

Recorrer todas las páginas entrega un snapshot consistente: aunque el dataset avance entre página y página, todas responden a la misma revisión.
El token solo vale para la misma consulta (moneda/serie/rango); usarlo en otra responde INVALID_PARAMS.
total es el total del rango a esa revisión, no el tamaño de la página.

Límite adicional: el rango from–to no puede exceder 5 años por consulta.

Caché

respuesta	política
`/v1/rates` sin `as_of_revision`	`no-store` — el dataset puede avanzar; no la guarde.
`/v1/rates` con `as_of_revision` o `page_token`	`immutable` + `ETag` (SHA-256 del body) — cacheable indefinidamente: la respuesta a una revisión fija no cambia jamás.
`/v1/evidence/{id}`	`immutable` + `ETag` = SHA-256 de los bytes — la evidencia es inmutable por diseño.
`/v1/observations/{id}`	`no-store` — la observación es inmutable, pero su representación incluye la cadena de supersesión y los eventos, que pueden crecer.