Errors

Errors return an HTTP status and a JSON envelope. Branch on the stable type string.

Envelope

{ "message": "…", "code": 401, "type": "user_invalid_credentials", "version": "1.0.0" }

`general_unauthorized_scope`	401 — missing/insufficient auth (e.g. no project header or key scope).
`user_invalid_credentials`	401 — wrong email/password.
`user_mfa_required`	401 — login needs an `otp`.
`user_unauthorized`	401 — authenticated but not permitted on this resource.
`user_already_exists`	409 — email/id already registered.
`document_not_found` / `collection_not_found`	404.
`document_already_exists`	409 — duplicate id or unique-index conflict.
`general_argument_invalid`	400 — validation failed (bad type, size, query, etc.).
`general_provider_unconfigured`	503 — a required provider (SMS/push) isn't set up.