Docs

Errors

Codes, body shape and what to do about each.

Every error returns { code, message, hint?, issues? }. The hint says how to fix it.

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.
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`.