Error codes

Every error response from Zautha is a problem details document (application/problem+json). Its code says what went wrong; its type is the address of the code’s page here.

{
  "type": "https://zautha.com/docs/errors/form_password_incorrect",
  "title": "Unprocessable Entity",
  "status": 422,
  "detail": "The password is incorrect.",
  "code": "form_password_incorrect",
  "errors": [{ "field": "password", "code": "form_password_incorrect", "message": "The password is incorrect." }],
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

• code is stable: branch on it, never on title or detail, which are for people and may change.
• errors is there when the problem concerns fields. Each entry names a field of the request, its own code and a message. A validation_failed problem lists every field that failed; most sign-in and sign-up errors name the one field they concern, with the same code.
• trace_id identifies the request in Zautha’s logs. Quote it when you write to support.
• A 429 carries a Retry-After header with the seconds to wait.
• Some codes add a member of their own: reverification (reverification_required), tasks (session_task_pending) and invitation_status (organization_invitation_not_pending).

The SDKs turn these responses into errors: ZauthaApiError in @zautha/js and @zautha/backend, and ZauthaApiException in Zautha.AspNetCore, each with the status, the code, the field errors and the trace id.

General

Code	Status	Meaning
bad_request	400	The request could not be read.
unauthenticated	401	The request needs a signed-in user or a valid secret key.
forbidden	403	The caller is known but may not do this.
resource_not_found	404	Nothing with this id exists here.
method_not_allowed	405	The path exists, but not with this HTTP method.
conflict	409	The generic code of a 409 without a more specific code.
unsupported_media_type	415	The request body is not JSON.
payload_too_large	413	The request body is larger than Zautha accepts.
rate_limited	429	The generic code of a 429 without a more specific code.
internal_error	500	Something went wrong on Zautha's side.
request_timeout	504	Zautha did not finish the request in time.
error	any	The response was not one of Zautha's problems.
validation_failed	400	One or more fields are not valid; errors[] names each one.
plan_limit_reached	403	A limit of the workspace's plan, or of a development instance, was reached.
too_many_requests	429	Too many requests in a short time; retry after Retry-After.
rate_limiter_unavailable	503	Zautha cannot check its rate limits right now, so it refuses the request.
instance_not_ready	503	The instance is still being set up.
idempotency_key_reused	422	This Idempotency-Key was already used for a different request.
idempotency_key_in_use	409	A request with this Idempotency-Key is still running.
origin_invalid	400	The request's Origin is not allowed for this instance.
cookie_invalid	400	The request carries a cookie name that Zautha refuses.
redirect_url_invalid	400	The redirect URL is not an allowed URL of this instance.

Field errors

These codes appear only as the code of an entry in errors, inside a validation_failed problem (or, for a custom domain’s host, a domain_invalid one).

Code	Status	Meaning
invalid_value	400	A field's value is not one the field accepts.
invalid_length	400	A field's value is too short or too long.
invalid_range	400	A number is outside its allowed range.
invalid_origin	400	An entry of the allowed origins is not an origin.
invalid_redirect_uri	400	An OAuth client's redirect URI is not allowed.
required	400	A required field is missing.
too_many	400	A list has more entries than allowed.

Sign-in and sign-up

Code	Status	Meaning
attempt_state_invalid	422	This step does not fit the sign-in or sign-up attempt's current state.
attempt_expired	422	The sign-in or sign-up attempt has expired.
form_param_invalid	400, 422	A parameter of the request is not valid for this step.
form_identifier_exists	422	An account already uses this email address.
form_identifier_not_found	422	No account has this email address or username.
form_username_exists	422	Another user has this username.
form_username_invalid	422	The username does not meet the rules.
form_email_invalid	422	This is not a valid email address.
form_password_length	422	The password is too short or too long.
form_password_pwned	422	The password appears in a known data breach.
form_password_context_word	422	The password contains a word from the account or the application.
form_password_incorrect	422	The password is not the account's password.
form_code_incorrect	422	The code is not correct.
verification_failed	422	The code was entered wrongly too many times.
verification_expired	422	The code or link has expired.
identifier_locked	429	This identifier is locked after repeated failures; retry after Retry-After.
user_banned	403, 422	The user is banned.
form_metadata_too_large	422	The metadata is larger than 8 KB.
form_ticket_invalid	422	The invitation or impersonation link is not valid any more.

Social sign-in, passkeys and bot protection

Code	Status	Meaning
passkey_origin_unsupported	422	Passkeys cannot work on this page's origin.
form_passkey_invalid	422	The passkey could not be verified.
strategy_disabled	422	This social sign-in provider is not enabled on the instance.
oauth_access_denied	422	The user refused access at the social provider.
oauth_token_exchange_error	422	The social provider did not complete the sign-in.
oauth_fetch_user_error	422	The account at the social provider could not be read.
oauth_identification_claimed	422	The provider's email belongs to an account it cannot be linked to automatically.
external_account_exists	422	This social account already belongs to a user.
oauth_account_already_connected	422	This provider account is already connected.
captcha_required	400	This step needs the bot check, and no token was sent.
captcha_invalid	400	The bot check token was refused.
captcha_unavailable	503	The bot check cannot be verified right now.

Sessions

Code	Status	Meaning
session_exists	422	The browser is already signed in.
reverification_required	403	The action needs the user to verify their identity again.
session_task_pending	403	The session has a task to finish before it gets a token.

OIDC

Code	Status	Meaning
consent_request_invalid	400	The consent request is not a valid authorization request of this instance.
id_token_hint_invalid	400	The logout cannot be tied to the current session.
oauth_client_public	422	A public OIDC client has no secret.

Organizations

Code	Status	Meaning
organizations_disabled	403	The instance has organizations turned off.
organization_minimum_permissions_needed	422	The change would leave an organization without anyone who can manage it.
organization_not_found	404	No organization has this id or slug in the instance.
organization_slug_taken	409	Another organization has this slug.
organization_slugs_disabled	403	The instance has organization slugs turned off.
already_organization_member	409	The user is already a member of the organization.
organization_membership_quota_exceeded	403	The organization has as many members and pending invitations as it may.
organization_role_in_use	409	The role is in use and cannot be deleted.
organization_system_permission_not_modifiable	403	System permissions cannot be changed or deleted.
organization_permission_limit_exceeded	422	The role has more custom permissions than fit in the session token.
organization_invitation_exists	409	This address already has a pending invitation to the organization.
organization_invitation_not_found	404	No invitation has this id or ticket.
organization_invitation_not_pending	409	The invitation is no longer pending.
organization_invitation_email_mismatch	403	The invitation is for another email address.
organization_creation_disabled	403	Users may not create organizations on this instance.
organization_creation_limit_exceeded	403	The user has created as many organizations as they may.
organization_delete_disabled	403	The organization's members may not delete it.
missing_organization_permission	403	The member's role does not have the permission this change needs.
personal_accounts_not_allowed	422	The instance requires every session to have an active organization.

Impersonation

Code	Status	Meaning
impersonation_forbidden	403	Impersonation is not allowed here.
impersonation_unavailable	422	This user cannot be impersonated as things stand.
actor_token_not_pending	409	The actor token is no longer pending.

Webhooks

Code	Status	Meaning
webhook_endpoint_limit	422	The instance already has its 20 webhook endpoints.
webhook_url_invalid	422	The webhook endpoint's URL is not allowed.

Workspaces and domains

These come from the dashboard.

Code	Status	Meaning
domain_invalid	400	The domain is not valid.
format	400	The host is not a domain name.
apex	400	The host is a domain itself, not a subdomain.
reserved	400	The host is under a Zautha domain.
domain_already_active	409	This host is already the instance's active domain.
domain_managed	409	This instance's host is managed by Zautha.
production_exists	409	The application already has a production instance.
workspace_personal	422	A personal workspace cannot be deleted.
workspace_not_empty	409	The workspace still has applications.
workspace_locked	403	This workspace is managed by Zautha.
workspace_last_owner	422	The workspace would be left without an owner.
already_workspace_member	409	A member of the workspace has this email address.
workspace_invitation_exists	409	This address already has an invitation to the workspace.
workspace_invitation_invalid	404	The workspace invitation is no longer valid.
workspace_invitation_email_mismatch	403	The workspace invitation is for another email address.

Billing

These come from the dashboard’s billing page.

Code	Status	Meaning
billing_already_subscribed	409	The workspace already has a subscription.
billing_no_customer	409	The workspace has no billing account yet.
billing_email_in_use	409	This address is another workspace's billing email.
billing_email_not_allowed	422	The billing email must be a verified address of a workspace owner.
billing_provider_error	502	The payment provider could not be reached.