Docs
Errors
Codes, body shape and what to do about each.
Every error is built to get you unblocked, not just to name the problem: { code, message, hint?, issues? } — the hint says exactly how to fix it, and issues points at the offending field.
| HTTP | code | Common cause |
|---|---|---|
| 401 | unauthenticated | Missing API key, malformed, revoked, or the prefix disagrees with the stored type/mode. |
| 403 | forbidden | pk_ key on an sk_ endpoint, Origin not allowed, or insufficient role. |
| 401 | key_expired | The key passed its expiry date. Create or rotate one. |
| 403 | secret_key_required | A pk_ key tried to record a consent with source IMPORT or MIGRATION. Call it from your server with an sk_ key. |
| 403 | insufficient_scope | The secret key is restricted to other scopes. See Console → Sites & API keys. |
| 403 | ip_not_allowed | The secret key has an IP allowlist and this request came from elsewhere. |
| 403 | origin_not_verified | LIVE pk_ key, Origin on a domain that is not verified yet. |
| 404 | not_found | The subject/resource does not exist (read endpoints do not create subjects). |
| 409 | idempotency_key_reused_with_different_body | Same Idempotency-Key, different body. |
| 422 | validation_failed | The body fails the Zod schema — see issues. |
| 429 | rate_limited | Slow down; respect Retry-After. |