Error Codes

All YorAuth API errors follow a consistent response envelope. This page catalogues every error code, its HTTP status, and how to resolve it.

Error Response Format

json

{
  "error": {
    "code": "AUTH_INVALID_CREDENTIALS",
    "message": "The email or password you entered is incorrect.",
    "details": {
      "field": "password",
      "reason": "password_mismatch"
    },
    "request_id": "req_1a2b3c4d5e6f",
    "timestamp": "2026-02-25T12:00:00Z",
    "documentation_url": "https://docs.yorauth.com/errors/auth-invalid-credentials"
  }
}

Field	Type	Description
`error.code`	string	Machine-readable error code (uppercase snake_case)
`error.message`	string	Human-readable message suitable for display
`error.details`	object	Optional additional context (field errors, retry info)
`error.request_id`	string	Unique identifier — include this when contacting support
`error.timestamp`	string	ISO 8601 timestamp when the error occurred
`error.documentation_url`	string	Link to documentation for this error

HTTP Status Codes

Status	When used
`400 Bad Request`	Invalid request syntax, missing fields, malformed values
`401 Unauthorized`	Authentication required or failed
`403 Forbidden`	Authenticated but not authorized
`404 Not Found`	Resource does not exist
`409 Conflict`	Duplicate resource or conflicting operation
`410 Gone`	Token or code has expired
`422 Unprocessable Entity`	Semantically invalid request
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server error
`502 Bad Gateway`	Upstream provider error
`503 Service Unavailable`	Maintenance or temporary outage

Authentication Errors (`AUTH_*`)

Code	HTTP	Description	Resolution
`AUTH_INVALID_CREDENTIALS`	401	Wrong email or password	Check email and password
`AUTH_TOKEN_EXPIRED`	401	Access token has expired	Call the refresh token endpoint
`AUTH_TOKEN_INVALID`	401	JWT is malformed, has an invalid signature, or wrong audience	Obtain a new token via login
`AUTH_TOKEN_REVOKED`	401	The session token has been explicitly revoked	User must log in again
`AUTH_INVALID_REFRESH_TOKEN`	401	Refresh token is invalid, expired, or already used	User must log in again
`AUTH_ACCOUNT_LOCKED`	429	Account temporarily locked after excessive failed login attempts	Wait for lockout to expire or reset password
`AUTH_ACCOUNT_SUSPENDED`	403	Account has been suspended by an administrator	Contact support
`AUTH_EMAIL_NOT_VERIFIED`	403	Email address has not been verified	Check email for verification link
`AUTH_MFA_REQUIRED`	401	Login requires MFA completion	Submit TOTP code via the verify MFA endpoint
`AUTH_INVALID_MFA_CODE`	401	TOTP code or backup code is incorrect	Check code in authenticator app
`AUTH_MFA_CHALLENGE_EXPIRED`	410	MFA challenge token has expired	Start login again
`AUTH_MFA_LOCKED`	429	Too many failed MFA attempts	Wait before retrying
`AUTH_INVALID_RESET_TOKEN`	400	Password reset token is invalid or does not match the email	Request a new reset link
`AUTH_RESET_TOKEN_EXPIRED`	410	Password reset token has expired	Request a new reset link
`AUTH_INVALID_VERIFICATION_TOKEN`	400	Email verification token is invalid	Request a new verification email
`AUTH_VERIFICATION_TOKEN_EXPIRED`	410	Email verification token has expired	Request a new verification email
`AUTH_VERIFICATION_RATE_LIMITED`	429	Too many verification email requests	Wait before requesting again
`AUTH_INVALID_MAGIC_LINK`	400	Magic link token is invalid or has already been used	Request a new magic link
`AUTH_MAGIC_LINK_EXPIRED`	410	Magic link token has expired	Request a new magic link
`AUTH_MAGIC_LINK_RATE_LIMITED`	429	Too many magic link requests	Wait before requesting again
`AUTH_PASSWORD_RESET_RATE_LIMITED`	429	Too many password reset requests	Wait 15 minutes before requesting again

Validation Errors (`VALIDATION_*`)

These errors occur when request data fails validation. The details field includes field-level information.

Code	HTTP	Description	Resolution
`VALIDATION_REQUIRED_FIELD`	400	A required field is missing	Include the required field
`VALIDATION_INVALID_FORMAT`	400	A field value does not match the expected format	Fix the field value
`VALIDATION_MULTIPLE_ERRORS`	400	Multiple fields failed validation	Fix all errors listed in `details.errors`
`VALIDATION_PASSWORD_TOO_WEAK`	422	Password does not meet the security policy	Choose a stronger password (min 8 chars, mixed case, number, special character)
`VALIDATION_PASSWORD_COMPROMISED`	422	Password found in known breach database	Choose a different password

Validation Error Detail Format

When there are multiple validation errors, the details field contains an array:

json

{
  "error": {
    "code": "VALIDATION_MULTIPLE_ERRORS",
    "message": "The request contains multiple validation errors.",
    "details": {
      "errors": [
        {
          "field": "email",
          "code": "VALIDATION_INVALID_FORMAT",
          "message": "The email field has an invalid format."
        },
        {
          "field": "password",
          "code": "VALIDATION_REQUIRED_FIELD",
          "message": "The password field is required."
        }
      ]
    },
    "request_id": "req_jkl789",
    "timestamp": "2026-02-25T12:00:00Z"
  }
}

Resource Errors (`RESOURCE_*`)

Code	HTTP	Description	Resolution
`RESOURCE_NOT_FOUND`	404	The requested resource does not exist	Verify the resource ID
`RESOURCE_ALREADY_EXISTS`	409	A resource with that identifier already exists	Use a different identifier or retrieve the existing resource
`RESOURCE_CONFLICT`	409	The operation conflicts with the current state of the resource	Resolve the conflict before retrying

Authorization Errors (`AUTHZ_*`)

Code	HTTP	Description	Resolution
`AUTHZ_PERMISSION_DENIED`	403	The authenticated token lacks the required permission	Request permission from an administrator
`AUTHZ_ROLE_NOT_FOUND`	404	The referenced role does not exist	Verify the role ID
`AUTHZ_ROLE_ALREADY_ASSIGNED`	409	The role is already assigned to this user with the same scope	No action needed — role is already active
`AUTHZ_ROLE_ASSIGNMENT_NOT_FOUND`	404	No matching role assignment found for the given user and scope	Verify the user ID, role ID, and scope

Resource-Specific Errors

Code	HTTP	Resource	Description
`USER_NOT_FOUND`	404	User	User does not exist in this application
`SESSION_NOT_FOUND`	404	Session	Session not found or already revoked
`WEBHOOK_NOT_FOUND`	404	Webhook	Webhook configuration not found
`API_KEY_NOT_FOUND`	404	API Key	API key not found
`API_KEY_ALREADY_REVOKED`	409	API Key	API key has already been revoked
`INVALID_PASSWORD`	422	User	Password verification failed (for change-password, disable MFA)
`MFA_INVALID_CODE`	422	MFA	TOTP code is incorrect during setup confirmation
`MFA_NOT_ENABLED`	400	MFA	MFA must be enabled before generating backup codes

OAuth Errors (`OAUTH_*`)

Code	HTTP	Description	Resolution
`OAUTH_PROVIDER_ERROR`	502	The upstream OAuth provider returned an error	Retry after a delay; contact support if persistent
`OAUTH_CONNECTION_NOT_FOUND`	404	No OAuth connection found for this user and provider	Connect the provider first
`OAUTH_STATE_MISMATCH`	400	OAuth CSRF state parameter does not match	Restart the OAuth flow

Rate Limit Errors (`RATE_LIMIT_*`)

Code	HTTP	Description	Resolution
`RATE_LIMIT_EXCEEDED`	429	Request rate limit exceeded	Wait for the `Retry-After` period before retrying

Rate limit responses include headers:

text

X-RateLimit-Limit: 10
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1708864800
Retry-After: 60

Server Errors (`SERVER_*`)

Code	HTTP	Description	Resolution
`SERVER_INTERNAL_ERROR`	500	Unexpected server error	Retry the request; include the `request_id` when contacting support
`SERVER_MAINTENANCE`	503	Service temporarily unavailable for maintenance	Check the `Retry-After` header for estimated completion

Tier / Billing Errors

Code	HTTP	Description	Resolution
`tier_limit_exceeded`	403	Application user or resource limit reached for current plan	Upgrade your plan or remove unused resources
`resource_limit_exceeded`	403	Application count limit reached for current plan	Upgrade your plan

OIDC Protocol Errors

OIDC endpoints return OAuth 2.0 / OIDC standard error codes (not the AUTH_* format):

Error	HTTP	Description
`invalid_client`	400	Client not found or inactive
`invalid_request`	400	Missing or invalid request parameter
`invalid_scope`	400	Requested scope is not allowed
`invalid_grant`	400	Authorization code or refresh token is invalid
`unsupported_grant_type`	400	Grant type is not supported