API Error Response Reference

Standard error envelopes, HTTP status meanings, and machine-readable AuthOS error codes.

AuthOS release 0.8.2 API v1 Latest-only documentation
Updated Jul 15, 2026
On this page

Error Response Format

All API errors return a JSON object with the following structure:

{
  "error": "Human-readable error message describing what went wrong",
  "error_code": "MACHINE_READABLE_ERROR_CODE",
  "timestamp": "2025-01-15T10:30:00Z"
}

Fields

Field Type Description
error string Human-readable description of the error
error_code string Machine-readable error code in SCREAMING_SNAKE_CASE
timestamp string ISO 8601 timestamp when the error occurred

Example

{
  "error": "Organization not found",
  "error_code": "NOT_FOUND",
  "timestamp": "2025-01-15T10:30:00.123Z"
}

HTTP Status Codes

The API uses standard HTTP status codes to indicate the general category of error.

2xx Success

Code Meaning Description
200 OK Success Request succeeded and response contains data
201 Created Resource Created New resource created successfully
204 No Content Success (No Response Body) Request succeeded, no content to return

4xx Client Errors

Code Meaning When It Occurs
400 Bad Request Invalid Request Malformed JSON, invalid parameters, business logic violation
401 Unauthorized Authentication Failed Missing, invalid, or expired JWT/API key
403 Forbidden Authorization Failed Valid credentials but insufficient permissions
404 Not Found Resource Not Found Requested resource doesn’t exist
409 Conflict Resource Conflict Resource already exists or state conflict
429 Too Many Requests Rate Limited Exceeded rate limit for endpoint

5xx Server Errors

Code Meaning When It Occurs
500 Internal Server Error Server Error Unexpected server-side error
503 Service Unavailable Service Down API temporarily unavailable (maintenance, overload)

Error Codes Reference

General Errors

Error Code HTTP Status Description Common Causes
BAD_REQUEST 400 Invalid request parameters Malformed JSON, missing required fields, invalid data types
UNAUTHORIZED 401 Authentication failed Missing token, invalid token, malformed Authorization header
FORBIDDEN 403 Insufficient permissions Valid credentials but wrong role/permissions
NOT_FOUND 404 Resource not found Invalid ID, deleted resource, wrong endpoint
INTERNAL_SERVER_ERROR 500 Server error Database error, unexpected exception

Authentication & Authorization Errors

Error Code HTTP Status Description Resolution
UNAUTHORIZED 401 Missing or invalid credentials Provide valid JWT or API key
TOKEN_EXPIRED 401 JWT has expired Refresh token using /api/auth/refresh
JWT_ERROR 401 Invalid JWT signature or format Obtain new token via authentication
FORBIDDEN 403 Insufficient permissions Request access or use account with proper role
ORGANIZATION_NOT_ACTIVE 403 Organization suspended or pending Contact platform admin

Business Logic Errors

Error Code HTTP Status Description Resolution
SERVICE_LIMIT_EXCEEDED 400 Max services reached for org tier Upgrade tier or delete unused services
TEAM_LIMIT_EXCEEDED 400 Max team members reached Upgrade tier or remove members
INVITATION_EXPIRED 400 Invitation link expired Request new invitation
DEVICE_CODE_EXPIRED 400 Device authorization code expired Start new device flow
DEVICE_CODE_PENDING 400 User hasn’t authorized device yet Continue polling

Database & Infrastructure Errors

Error Code HTTP Status Description Resolution
DATABASE_ERROR 500 Database operation failed Retry request; contact support if persists
OAUTH_ERROR 500 OAuth provider error Check provider status; retry later
STRIPE_ERROR 500 Billing system error Check Stripe status; contact support
AUDIT_ERROR 500 Audit logging failed Request succeeded but not logged; report to support