Skip to content

Error codes ​

The envelope ​

Every failed request returns JSON shaped like this:

json
{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Email or password is incorrect.",
    "requestId": "4f9b2df3-8a60-45ba-a5c0-b8a144b03d3a",
    "details": [{ "field": "email", "issue": "invalid_format" }]
  }
}
FieldMeaning
codeA stable machine-readable code from the table below. Branch on this.
messageA human-readable sentence. It may change or be localized: never compare it
requestIdThe same id as the X-Request-Id response header. Quote it when you look in the logs
detailsOnly for VALIDATION_FAILED and PASSWORD_POLICY_VIOLATION. Describes only the input the client sent

Errors are never more specific than the table allows: there is no "user not found" versus "wrong password", and no "token expired" versus "token already used".

The codes ​

CodeHTTPWhenHow to handle it
VALIDATION_FAILED400Malformed or missing input, or malformed JSONShow the field problems from details
PASSWORD_POLICY_VIOLATION400The password breaks the policy (too short, too long, too common)Show the rule from details
TOKEN_INVALID400A one-time token failed: expired, already used, or unknown. Always the same codeAsk the user to request a new link
INVALID_CREDENTIALS401Unknown user, deleted user or wrong password. Identical for all causesShow "email or password is incorrect"
UNAUTHENTICATED401No valid session for a protected operationSend the user to sign in
EMAIL_NOT_VERIFIED403The password is correct but the account is pendingOffer to resend the verification email
ACCOUNT_UNAVAILABLE403The password is correct but the account is suspended or disabledTell the user to contact support
FORBIDDEN403Signed in but not permittedShow "not allowed"
REAUTHENTICATION_REQUIRED403The operation needs a recent password entry (admin routes)Ask the user to sign in again
CSRF_FAILED403The origin or CSRF header check failedSend the X-SelfAuth-CSRF header; check trusted origins. See Troubleshooting
NOT_FOUND404The resource does not exist, or the user may not know it existsShow "not found"
EMAIL_TAKEN409Registering a known email, only when registration.revealExistingEmail is onTell the user to sign in
CONFLICT409A state conflict, for example removing the last administratorShow the conflict
PAYLOAD_TOO_LARGE413The body is larger than http.bodyLimitBytesSend less data
RATE_LIMITED429A rate limit was exceeded. The Retry-After header says how many seconds to waitWait, then retry
INTERNAL_ERROR500An unexpected failure. No internals are exposedRetry later; look the requestId up in the server log

The frontend client adds two codes of its own: NETWORK_ERROR when the request didn't complete, and UNEXPECTED_RESPONSE when the server's answer wasn't understood.

Why some codes are vague ​

Nobody should be able to tell whether an email has an account. The codes that could give that away are intentionally vague:

  • INVALID_CREDENTIALS is the same for an unknown email, a deleted account and a wrong password.
  • EMAIL_NOT_VERIFIED and ACCOUNT_UNAVAILABLE only appear after the password has been verified, so they tell someone who doesn't know the password nothing.
  • EMAIL_TAKEN exists only as an opt-in trade-off.
  • Registration, password reset requests and verification resends answer 202 whatever the email.

Handling errors in your own routes ​

Return your own errors in the same envelope so clients can treat them like SelfAuth's:

json
{ "error": { "code": "VALIDATION_FAILED", "message": "item is required.", "requestId": "..." } }

In Express, throw new HttpError(status, code, message) from src/http/errors.ts and the app's error handler formats it. Don't leak stack traces, SQL or file paths.

SelfAuth is MIT licensed. Generated code is also offered under 0BSD.