Error Codes Reference

Complete reference of all error codes returned by the AuthOS API.

Error Response Format

All errors follow this structure:

{
  "error": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE",
  "timestamp": "2025-01-15T10:30:00Z"
}

Code	HTTP	Description
`BAD_REQUEST`	400	Invalid request parameters or malformed JSON
`UNAUTHORIZED`	401	Missing or invalid authentication
`FORBIDDEN`	403	Valid credentials but insufficient permissions
`NOT_FOUND`	404	Requested resource does not exist
`CONFLICT`	409	Resource already exists or state conflict
`RATE_LIMIT_EXCEEDED`	429	Too many requests
`INTERNAL_SERVER_ERROR`	500	Unexpected server error

Code	HTTP	Description	Resolution
`UNAUTHORIZED`	401	Missing or invalid credentials	Provide valid JWT or API key
`TOKEN_EXPIRED`	401	JWT has expired	Refresh using `/api/auth/refresh`
`JWT_ERROR`	401	Invalid JWT signature or format	Obtain new token
`INVALID_CREDENTIALS`	401	Wrong email or password	Verify credentials
`EMAIL_NOT_VERIFIED`	401	Account email not verified	Check email for verification link
`ACCOUNT_LOCKED`	401	Too many failed attempts	Wait or contact support

Code	HTTP	Description	Resolution
`FORBIDDEN`	403	Insufficient permissions	Use account with proper role
`ORGANIZATION_NOT_ACTIVE`	403	Organization suspended/pending	Contact platform admin
`NOT_ORGANIZATION_MEMBER`	403	Not a member of organization	Request membership
`PLATFORM_OWNER_REQUIRED`	403	Platform owner access needed	Use platform owner account

Code	HTTP	Description	Resolution
`INVALID_EMAIL`	400	Invalid email format	Provide valid email
`WEAK_PASSWORD`	400	Password doesn’t meet requirements	Use stronger password (min 8 chars)
`INVALID_SLUG`	400	Invalid slug format	Use alphanumeric, hyphens, underscores only
`RESERVED_SLUG`	400	Slug is reserved	Choose different slug
`SLUG_TOO_SHORT`	400	Slug less than 3 characters	Use longer slug
`SLUG_TOO_LONG`	400	Slug more than 50 characters	Use shorter slug
`NAME_TOO_SHORT`	400	Name less than 2 characters	Use longer name
`NAME_TOO_LONG`	400	Name more than 100 characters	Use shorter name
`INVALID_URL`	400	URL format invalid	Provide valid URL with http(s)

Code	HTTP	Description	Resolution
`NOT_FOUND`	404	Resource not found	Verify ID and permissions
`ALREADY_EXISTS`	409	Resource already exists	Use different identifier
`SERVICE_LIMIT_EXCEEDED`	400	Max services for tier	Upgrade tier or delete services
`TEAM_LIMIT_EXCEEDED`	400	Max members for tier	Upgrade tier or remove members
`USER_ALREADY_EXISTS`	409	User with email exists	Use different email or login
`INVITATION_EXPIRED`	400	Invitation link expired	Request new invitation
`INVITATION_ALREADY_ACCEPTED`	400	Invitation already used	No action needed

Code	HTTP	Description	Resolution
`MFA_REQUIRED`	401	MFA verification needed	Complete MFA verification
`INVALID_MFA_CODE`	400	Wrong TOTP or backup code	Enter correct code
`MFA_NOT_ENABLED`	400	MFA not set up for user	Set up MFA first
`MFA_ALREADY_ENABLED`	400	MFA already active	No action needed
`NO_BACKUP_CODES`	400	No backup codes available	Regenerate backup codes

Code	HTTP	Description	Resolution
`DEVICE_CODE_EXPIRED`	400	Device code expired	Start new device flow
`DEVICE_CODE_PENDING`	400	User hasn’t authorized yet	Continue polling
`INVALID_DEVICE_CODE`	400	Device code not found	Start new device flow
`INVALID_GRANT_TYPE`	400	Wrong grant_type value	Use correct grant type

Code	HTTP	Description	Resolution
`OAUTH_ERROR`	500	OAuth provider error	Check provider status
`OAUTH_STATE_MISMATCH`	400	CSRF state mismatch	Restart OAuth flow
`OAUTH_CODE_EXPIRED`	400	Authorization code expired	Restart OAuth flow
`PROVIDER_NOT_CONFIGURED`	400	OAuth provider not set up	Configure provider credentials

Code	HTTP	Description	Resolution
`SAML_NOT_CONFIGURED`	400	SAML not configured	Configure SAML settings
`INVALID_SAML_RESPONSE`	400	SAML response invalid	Check IdP configuration
`SAML_SIGNATURE_INVALID`	400	SAML signature failed	Verify certificates
`SAML_EXPIRED`	400	SAML assertion expired	Retry authentication

Code	HTTP	Description	Resolution
`INVALID_SCIM_TOKEN`	401	SCIM token invalid/expired	Create new SCIM token
`SCIM_USER_EXISTS`	409	User already exists	Update existing user
`SCIM_USER_NOT_FOUND`	404	SCIM user not found	Check user ID
`SCIM_FILTER_INVALID`	400	Invalid filter syntax	Fix filter expression

Code	HTTP	Description	Resolution
`INVALID_WEBHOOK_URL`	400	URL not HTTP(S)	Use http:// or https://
`INVALID_WEBHOOK_EVENT`	400	Unknown event type	Use valid event type
`WEBHOOK_NAME_EXISTS`	409	Webhook name taken	Use different name

Code	HTTP	Description	Resolution
`DATABASE_ERROR`	500	Database operation failed	Retry; contact support if persists
`STRIPE_ERROR`	500	Billing system error	Check Stripe status
`EMAIL_SEND_FAILED`	500	Email delivery failed	Check SMTP configuration
`ENCRYPTION_ERROR`	500	Encryption/decryption failed	Contact support

Status	Meaning	Common Causes
`200`	Success	Request completed
`201`	Created	Resource created
`204`	No Content	Success, no response body
`400`	Bad Request	Invalid input, validation failure
`401`	Unauthorized	Missing/invalid authentication
`403`	Forbidden	Valid auth, wrong permissions
`404`	Not Found	Resource doesn’t exist
`409`	Conflict	Duplicate resource
`429`	Too Many Requests	Rate limited
`500`	Server Error	Unexpected error
`503`	Service Unavailable	Maintenance/overload