Documentación / API v2

Errores de la v2

Todo error de la v2 viene en el mismo formato y con un code estable. Escribe el manejo sobre el code; detail es texto para personas y puede cambiar.

01 / problem+json

Un formato para todos los errores

Las respuestas de error usan application/problem+json (RFC 9457). Además de los campos estándar, traen code, request_id y el contexto de lo que se rechazó.

GET /api/v2/days/2026-03-25?book=loc_2015&include=readings.audio400

{
  "type": "https://estevao.caminhoanglicano.com.br/docs/v2/errors#invalid-include",
  "title": "Invalid include",
  "status": 400,
  "code": "INVALID_INCLUDE",
  "detail": "Include inválido: readings.audio.",
  "documentation_url": "https://estevao.caminhoanglicano.com.br/docs/v2",
  "request_id": "6f0c2c1e-…",
  "unknown": ["readings.audio"],
  "allowed": ["readings", "readings.text", "readings.morning", "readings.evening",
              "readings.alternatives", "collect", "collect.text", "celebrations", "explanation"]
}

— allowed lista los valores aceptados en los errores de include, fields, service y text_format; max_days aparece en el de rango.
— type apunta a la fila de este código en la tabla de abajo.
— Al pedir ayuda, envía el request_id: localiza la petición en los logs.
— La excepción es el 429: el limitador responde en application/json, con error.code RATE_LIMIT_EXCEEDED y el encabezado Retry-After.

02 / Códigos

Todos los códigos

code	HTTP	Cuándo ocurre
`MISSING_API_KEY`	401	La petición no trajo X-API-Key, o la clave no es válida, está inactiva o expiró.
`MISSING_PRAYER_BOOK`	400	Falta book en un recurso que depende del libro de oración.
`UNKNOWN_PRAYER_BOOK`	422	book no corresponde a ningún libro disponible para claves de API.
`INVALID_INCLUDE`	400	Un nombre en include no lo ofrece este endpoint. Mira allowed.
`INVALID_FIELDS`	400	Un tipo o atributo en fields no existe en este endpoint.
`INVALID_DATE`	400	La fecha no existe o no está en formato AAAA-MM-DD; en /celebrations, también cuando month y day no forman una fecha.
`MISSING_DATE_RANGE`	400	/days se llamó sin from y to y sin year.
`INVALID_DATE_RANGE`	400	El rango está invertido: from viene después de to.
`RANGE_TOO_LARGE`	400	El rango supera el máximo del endpoint: 366 días, o 31 con readings.text o explanation. Mira max_days.
`INVALID_SERVICE`	400	service no es uno de los oficios aceptados. Mira allowed.
`INVALID_TEXT_FORMAT`	400	text_format no es verses, plain ni markdown.
`MISSING_REFERENCE`	400	/passages se llamó sin ref.
`MISSING_BIBLE_VERSION`	400	/passages se llamó sin bible.
`UNKNOWN_BIBLE_VERSION`	422	bible no corresponde a ninguna versión disponible.
`PASSAGE_NOT_FOUND`	404	La referencia no tiene texto en la versión pedida.
`INVALID_CELEBRATION_TYPE`	422 · 400	422 cuando type no es un tipo de celebración (mira allowed); 400 cuando es sunday sin year.
`INVALID_CELEBRATION_DATE`	400	day se envió sin month ni year.
`INVALID_SEARCH_QUERY`	400	q está vacío o supera el tamaño máximo, informado en max_length.
`INVALID_BOOLEAN`	400	movable no es true ni false.
`INVALID_LIMIT`	400	limit está fuera del rango de 1 a 100.
`INVALID_CURSOR`	400	El cursor está corrupto o se generó con otros filtros u otro book.
`CELEBRATION_NOT_FOUND`	404	No hay celebración con ese id en el libro indicado.
`RATE_LIMIT_EXCEEDED`	429	La clave superó el límite diario o por minuto de su plan. Espera el tiempo de Retry-After.

La ausencia de contenido no es un error: una fecha sin lecturas responde 200 con readings vacío, y una búsqueda sin resultados responde 200 con data vacío.