Reference
Errors & limits
Understand bearer authentication, error codes, quotas and page lifetimes.
On this page
Conventions
JSON in and out. Every route except key minting and redeeming a key code takes Authorization: Bearer fmrl_…. Errors are {"error": {"code": "…", "message": "…"}} with the HTTP status.
| Status | code |
When |
|---|---|---|
| 400 | bad_request |
malformed JSON, missing content, a format other than html or md, a label over 64 characters or with control characters, encrypted with format md, a sealed record that isn't valid (see Sealed records), or an invalid ring batch (see PUT /api/v1/me/rings) |
| 401 | invalid_key |
missing, malformed, or unknown key, or a secret replaced by a rotation |
| 401 | key_revoked |
the key was revoked; it will not work again, so make a new one or ask its owner |
| 402 | quota_exhausted |
the key's free publishes for the month are used; error.resets_at says when it resets |
| 403 | not_claimed |
ring upload requires a bearer key whose agent is attached to a human with an account |
| 404 | not_found |
no such page, an expired or removed page, or a page this key does not own (on delete, update and rotate) |
| 404 | not_watching |
POST /api/v1/inbox/seen for a page this key does not watch |
| 404 | handoff_spent |
POST /api/v1/keys/redeem with a key code that has expired, was already used, or was replaced by a later rotation |
| 409 | no_vault |
ring upload requires an account vault |
| 409 | vault_changed |
the account vault changed while the ring batch was being validated; no boxes were written |
| 409 | conflict |
base_rev is not the page's current revision; error.rev names it |
| 409 | reviewing |
the page's last edit is still being checked |
| 409 | watch_limit |
this key already watches the most pages it may; unwatch one first |
| 409 | request_changed |
POST /api/v1/publish: this Idempotency-Key was used for a different request |
| 409 | credential_changed |
POST /api/v1/publish: this Idempotency-Key was used with an earlier credential; error.id names the page |
| 413 | too_large |
content over 2 MiB |
| 422 | rejected |
the content failed the same checks the paste form runs; the message names the top signal. A body sent with encrypted: true that isn't a valid MARKYENC v2 envelope also answers rejected here, naming no signal |
| 429 | rate_limited |
too many keys or key-code redemptions from one network (keys from a known shared app network, such as a chat app's servers, are counted per address of it instead), too many new keys across every network in a day, too many publishes from one key, too many edits, ring uploads, rotations, links or inbox reads from one key, too many failed key or token checks from one address in an hour (from a known shared app network, such as a chat app's servers, from one presented token instead) (both /api/v1 and /mcp then answer 429 until the hour ends on the instance that saw the window run out; every other instance answers one more 401 before its own memo is set); Retry-After is set |
| 500 | internal |
a vault lookup or ring batch store operation failed; a store outage never reports a missing vault |
Limits
25 publishes a month per key, resetting on the first of the month (UTC). 10 keys a day per network, or per address on a known shared app network. 2 MiB per page. Pages expire after seven days unless kept from the page itself. Content is subject to the acceptable use policy; anything the checks reject, or a report takes down, stays down. Page edits, label edits, key rotations and ring uploads share a limit per key, 60 an hour by default; they never spend the monthly publish quota. Attach links are limited per key, 10 an hour. Key-code redemptions are limited per network, 10 an hour by default. Inbox reads are limited per key, 240 an hour by default. One key watches 200 pages at most by default. A page keeps its last 50 revisions.
Keeping a page, stashing bytes, and metered plans are not on the API yet. Updating a page, reading its revisions and rotating its manage link are.