Error Codes Reference

AuthOS uses structured error responses with machine-readable error codes. This reference lists all possible error_code values returned by the API.

Error Response Format

All API errors return a non-2xx HTTP status code and a JSON body:

{
  "error": "Detailed description of the error",
  "error_code": "MACHINE_READABLE_CODE",
  "timestamp": "2025-01-15T10:30:00Z"
}

Error Code	HTTP	Description
`UNAUTHORIZED`	401	Missing or invalid authentication credentials.
`TOKEN_EXPIRED`	401	The JWT access token has expired. Use the refresh token to obtain a new one.
`JWT_ERROR`	401	The JWT token is malformed or its signature is invalid.
`FORBIDDEN`	403	Authenticated, but lacks sufficient permissions for the requested resource.
`ORGANIZATION_NOT_ACTIVE`	403	The organization is currently pending approval or has been suspended.
`FEATURE_NOT_AVAILABLE_IN_TIER`	403	The requested feature is not included in the organization’s current tier.

Error Code	HTTP	Description
`BAD_REQUEST`	400	The request is malformed, missing required fields, or fails validation.
`NOT_FOUND`	404	The requested resource (user, organization, service, etc.) does not exist.
`DUPLICATE_CONSTRAINT`	400	A resource with the same unique identifier (e.g., email or slug) already exists.
`TOO_MANY_REQUESTS`	429	Rate limit exceeded for the current endpoint.

Error Code	HTTP	Description
`DEVICE_CODE_PENDING`	400	Authorization is still pending. The client should continue polling.
`DEVICE_CODE_EXPIRED`	400	The device code has expired. The user must restart the login flow.

Error Code	HTTP	Description
`SERVICE_LIMIT_EXCEEDED`	400	Organization has reached the maximum number of services for its tier.
`TEAM_LIMIT_EXCEEDED`	400	Organization has reached the maximum number of members for its tier.
`INVITATION_EXPIRED`	400	The invitation link has expired or has already been used.

Error Code	HTTP	Description
`INTERNAL_SERVER_ERROR`	500	An unexpected error occurred on the server.
`DATABASE_ERROR`	500	A database operation failed unexpectedly.
`OAUTH_ERROR`	500	Communication with an external OAuth provider failed.
`STRIPE_ERROR`	500	An error occurred while communicating with the billing provider (Stripe).
`BILLING_ERROR`	500	General error related to billing or subscription processing.
`AUDIT_ERROR`	500	Failed to record an audit log entry.
`IO_ERROR`	500	File system or network I/O failure.
`GENERIC_ERROR`	500	An unspecified internal error occurred.