Errors & status codes

Status codes

• 200 — success.
• 204 — response to OPTIONS preflight; no body.
• 400 — malformed body, missing query param, or an app-level guard fired (for example "Form not published"). Body is JSON with an error field.
• 401 — missing/malformed Authorization, revoked key, or a signature failure. See Authentication for the full signature-failure list.
• 402 — plan quota exceeded — currently "Device quota exceeded for this app's plan" on /register.
• 403 — the key exists but does not belong to this app / environment, or the endpoint's capability is not on this plan.
• 404 — either the app / device / form / post could not be found for this key, or the URL path is wrong. Do NOT reduce this to "trailing slash" — always verify the app-scoped resource exists too.
• 413 — request body exceeded the endpoint's byte cap (16 KiB / 32 KiB / 64 KiB / 128 KiB / 256 KiB depending on route).
• 429 — rate limited. Body is { "error": "rate_limited" }; respect Retry-After (seconds). /session is deliberately exempt.
• 500 — server error such as "Register failed" or "Failed to load inbox". Retry with backoff.
• 503 — "Signature store unavailable" when nonce persistence fails. Retry.