Documentation / API v2

v2 errors

Every v2 error has the same shape and a stable code. Build your handling on code; detail is text for people and may change.

01 / problem+json

One shape for every error

Error responses use application/problem+json (RFC 9457). Besides the standard members they carry code, request_id and the context of what was rejected.

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 lists the accepted values on include, fields, service and text_format errors; max_days appears on the range error.
— type points to this code's row in the table below.
— When asking for help, send the request_id: it finds the request in the logs.
— The exception is 429: the rate limiter answers application/json, with error.code RATE_LIMIT_EXCEEDED and a Retry-After header.

02 / Codes

Every code

code	HTTP	When it happens
`MISSING_API_KEY`	401	The request had no X-API-Key, or the key is invalid, inactive or expired.
`MISSING_PRAYER_BOOK`	400	book is missing on a resource that depends on the prayer book.
`UNKNOWN_PRAYER_BOOK`	422	book matches no book available to API keys.
`INVALID_INCLUDE`	400	A name in include is not offered by this endpoint. See allowed.
`INVALID_FIELDS`	400	A type or attribute in fields does not exist on this endpoint.
`INVALID_DATE`	400	The date does not exist or is not YYYY-MM-DD; on /celebrations, also when month and day do not form a date.
`MISSING_DATE_RANGE`	400	/days was called without from and to and without year.
`INVALID_DATE_RANGE`	400	The range is inverted: from comes after to.
`RANGE_TOO_LARGE`	400	The range exceeds the endpoint's maximum: 366 days, or 31 with readings.text or explanation. See max_days.
`INVALID_SERVICE`	400	service is not one of the accepted offices. See allowed.
`INVALID_TEXT_FORMAT`	400	text_format is not verses, plain or markdown.
`MISSING_REFERENCE`	400	/passages was called without ref.
`MISSING_BIBLE_VERSION`	400	/passages was called without bible.
`UNKNOWN_BIBLE_VERSION`	422	bible matches no available translation.
`PASSAGE_NOT_FOUND`	404	The reference has no text in the requested translation.
`INVALID_CELEBRATION_TYPE`	422 · 400	422 when type is not a celebration type (see allowed); 400 when it is sunday without year.
`INVALID_CELEBRATION_DATE`	400	day was sent without month or year.
`INVALID_SEARCH_QUERY`	400	q is empty or longer than the maximum, reported in max_length.
`INVALID_BOOLEAN`	400	movable is neither true nor false.
`INVALID_LIMIT`	400	limit is outside 1 to 100.
`INVALID_CURSOR`	400	The cursor is corrupt or was issued for other filters or another book.
`CELEBRATION_NOT_FOUND`	404	No celebration has that id in the given book.
`RATE_LIMIT_EXCEEDED`	429	The key went over its plan's daily or per-minute limit. Wait for Retry-After.

No content is not an error: a date without readings answers 200 with an empty readings list, and a search with no match answers 200 with empty data.