FAQ and troubleshooting

Why does the note return 404?#

Keys see only published notes. The note is probably still a draft or in review. Subscribe to note.published or retry later. See notes and outputs.

Why is my teaching still processing?#

Long recordings take minutes. Poll GET /v1/teachings/{teaching} and read status. If it is failed, failure_reason says why. If it stays in awaiting_upload, the upload was never completed: call POST /v1/teachings/{teaching}/upload with the key.

I get 401#

The key is wrong, revoked or expired. Check that you send Authorization: Bearer <key> and that the key has not passed expires_at. A test key against a live church (or the reverse) is also refused.

I get 403#

Read error.code. permission_denied means the key lacks the scope on the operation page, or its IP allowlist excludes your server, or the church is suspended. not_entitled means the plan lacks the feature. origin_not_allowed is the widget allowlist.

I get 402#

quota_exceeded means the plan's allowance is used up; ai_budget_exhausted means the AI budget is. Neither is a bug in your code. See errors.

I get 422 with idempotency_key_reused#

You sent the same Idempotency-Key with a different body. Use a new key for a different request.

My webhook signature never matches#

Check you use the raw body, the whole secret including whsec_, the webhook-id.webhook-timestamp.body content and base64 of the HMAC. After a rotation, either secret may have signed. See webhooks.

Can I use another Bible translation?#

No. Folio carries the King James Version only. Any other translation is not found.

Can I read drafts through the API?#

No. Drafts and notes in review stay with the church until they are approved.

Which host do I call?#

The one shown at the top of the API reference. Live and sandbox churches use the same host; the key type chooses which you reach.

How do I report a problem?#

Email support with the request_id from the failing response (error.request_id, or the X-Request-Id header).