Errors · API docs

Every failure has the same shape and Content-Type: application/json:

Code

{
  "status": false,
  "message": "That API key does not have the notes:read scope.",
  "error": {
    "code": "permission_denied",
    "status": 403,
    "request_id": "req_b337770ecebe03b03a88a8998b59263d",
    "details": [{ "field": "name", "code": "required", "message": "name is required" }],
    "meta": { "reason": "idempotency_key_reused" }
  }
}

message is written for a person; do not parse it. Branch on error.code, which is a closed list. details lists per-field problems on validation errors. meta.reason refines a code (for example the idempotency cases). New codes can be added within /v1, so treat an unknown code as a generic failure of its HTTP status.

Error codes#

The table is the list in the OpenAPI document (ErrorCode).

Code	HTTP	Cause	What to do
`invalid_argument`	400	A malformed id, cursor, header or body.	Fix the request; do not retry it unchanged.
`unauthenticated`	401	The key is missing, malformed, revoked or expired.	Send a valid key, or create a new one.
`permission_denied`	403	The key lacks the scope, the church is suspended, the address is outside the key's allowlist, or deletion is scheduled.	Check the scope on the operation and the key's allowlist.
`not_entitled`	403	The church's plan does not include this feature.	Upgrade the plan, or stop calling the feature.
`disabled_by_church`	403	The church turned the feature off in its own settings.	Ask the church to turn it on.
`origin_not_allowed`	403	The page that called is not in the widget's allowlist.	Add the origin to the widget allowlist.
`not_found`	404	Not in this church, or not visible to a key yet (for example a note that is not published).	Check the id and the church.
`already_exists`	409	A thing with that identity exists.	Read the existing one.
`conflict`	409	The request clashes with current state, including an idempotent request still running.	Wait `Retry-After` seconds and send the same request.
`stale_version`	412	The row changed since you read it, so your `If-Match` `row_version` is out of date.	Read it again, merge, retry.
`failed_precondition`	412	A required condition is not met yet.	Read the message; usually a step comes first.
`validation`	422	A field failed validation, or an `Idempotency-Key` was reused with a different body.	Read `error.details`.
`step_up_required`	428	A missing `If-Match` header, or a console action that needs a recent sign-in.	Send `If-Match`, or sign in again.
`quota_exceeded`	402	The plan's hours, notes or Ask allowance is used up.	Wait for the next cycle, add capacity or upgrade.
`plan_required`	409	The church has no active plan for this action.	Start a plan in the console.
`payment_failed`	402	A payment did not go through.	Update the payment method.
`overage_ceiling_reached`	402	Metered overage reached the ceiling the church set.	Raise the ceiling or wait for the next cycle.
`ai_budget_exhausted`	402	The monthly AI budget, or a sandbox church's test budget, is used up.	Raise the budget, wait for the next month, or create a new sandbox church.
`rate_limited`	429	Too many requests for the key, the church or the device.	Wait `Retry-After` seconds, then back off.
`unavailable`	503	A dependency is down, or the church is not set up for this yet.	Retry with backoff and an `Idempotency-Key`.
`internal`	500	Something went wrong at Folio.	Retry once; if it persists quote `error.request_id` to support.

Booth routes also answer 426 when the booth's contract version is no longer supported; see booth devices.

Idempotency errors#

Situation	Response
Same `Idempotency-Key`, different body	`422 validation` with `error.meta.reason` of `idempotency_key_reused`
Same key while the first request is still running	`409 conflict` with `error.meta.reason` of `idempotency_in_progress` and `Retry-After`
Replaying a request whose response held a one-time secret	`409` with `error.meta.reason` of `idempotency_secret_unavailable`; use a new key

See idempotency.

Preconditions#

Some console routes that edit notes and outputs use optimistic concurrency. They need If-Match: <row_version>: without it the answer is 428, and with an out-of-date version it is 412 stale_version with the current row_version in error.meta. The church API does not edit notes or outputs today, so you will mostly meet these in console tooling.

What to retry#

Retry	Do not retry
`429` after `Retry-After` seconds	`400`, `401`, `403`, `404`, `422` as they stand
`503`, `500` and network failures, with backoff	`402` until something changes (a new cycle, more allowance)
`409` with `Retry-After`	`412`: read again first

Always send an Idempotency-Key on calls you retry so a retry cannot do the work twice.

Verified against API version 0.0.0-dev. Generated from the live OpenAPI document.