Documentação / API v2

Erros da v2

Todo erro da v2 vem no mesmo formato e com um code estável. Escreva o tratamento em cima do code; o detail é texto para pessoas e pode mudar.

01 / problem+json

Um formato para todos os erros

As respostas de erro usam application/problem+json (RFC 9457). Além dos campos padrão, trazem code, request_id e o contexto do que foi rejeitado.

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 os valores aceitos nos erros de include, fields, service e text_format; max_days aparece no de intervalo.
— type aponta para a linha deste código na tabela abaixo.
— Ao pedir ajuda, envie o request_id: ele localiza a requisição nos logs.
— A exceção é o 429: o limitador responde em application/json, com error.code RATE_LIMIT_EXCEEDED e o cabeçalho Retry-After.

02 / Códigos

Todos os códigos

code	HTTP	Quando acontece
`MISSING_API_KEY`	401	A requisição não trouxe X-API-Key, ou a chave não é válida, está inativa ou expirou.
`MISSING_PRAYER_BOOK`	400	Falta book num recurso que depende do livro de oração.
`UNKNOWN_PRAYER_BOOK`	422	book não corresponde a nenhum livro disponível para chaves de API.
`INVALID_INCLUDE`	400	Um nome em include não é aceito por este endpoint. Veja allowed.
`INVALID_FIELDS`	400	Um tipo ou atributo em fields não existe neste endpoint.
`INVALID_DATE`	400	A data não existe ou não está no formato AAAA-MM-DD; em /celebrations, também quando month e day não formam uma data.
`MISSING_DATE_RANGE`	400	/days foi chamado sem from e to e sem year.
`INVALID_DATE_RANGE`	400	O intervalo está invertido: from vem depois de to.
`RANGE_TOO_LARGE`	400	O intervalo passa do máximo do endpoint: 366 dias, ou 31 com readings.text ou explanation. Veja max_days.
`INVALID_SERVICE`	400	service não é um dos ofícios aceitos. Veja allowed.
`INVALID_TEXT_FORMAT`	400	text_format não é verses, plain nem markdown.
`MISSING_REFERENCE`	400	/passages foi chamado sem ref.
`MISSING_BIBLE_VERSION`	400	/passages foi chamado sem bible.
`UNKNOWN_BIBLE_VERSION`	422	bible não corresponde a nenhuma versão disponível.
`PASSAGE_NOT_FOUND`	404	A referência não tem texto na versão pedida.
`INVALID_CELEBRATION_TYPE`	422 · 400	422 quando type não é um dos tipos de celebração (veja allowed); 400 quando é sunday sem year.
`INVALID_CELEBRATION_DATE`	400	day foi informado sem month nem year.
`INVALID_SEARCH_QUERY`	400	q está vazio ou passa do tamanho máximo, informado em max_length.
`INVALID_BOOLEAN`	400	movable não é true nem false.
`INVALID_LIMIT`	400	limit está fora do intervalo de 1 a 100.
`INVALID_CURSOR`	400	O cursor está corrompido ou foi gerado com outros filtros ou outro book.
`CELEBRATION_NOT_FOUND`	404	Não há celebração com esse id no livro informado.
`RATE_LIMIT_EXCEEDED`	429	A chave passou do limite diário ou do limite por minuto do plano. Espere o tempo de Retry-After.

Ausência de conteúdo não é erro: uma data sem leituras responde 200 com readings vazio, e uma busca sem resultado responde 200 com data vazio.