Bearer Authentication – Common Auth Errors

This section standardizes handling of authentication and authorization failures across all API clients. It covers the two most common HTTP status codes returned when using Bearer tokens, provides a canonical error response shape, realistic examples, and clear remediation steps.

Common Error Status Codes

Below are the primary status codes related to Bearer token issues:

These defaults align with our interactive API editor’s common response data .

Error Response Format

All authentication and authorization errors share a consistent JSON structure:

{
  "error": {
    "message": "<Human-readable description>",
    "code": "<machine_readable_error_code>"
  }
}

• message: Brief description of the failure.
• code: Standardized error identifier in snake_case.

Examples

401 Unauthorized

Occurs when the Authorization header is missing or the token is invalid/expired.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "error": {
    "message": "Authentication required",
    "code": "unauthorized"
  }
}

403 Forbidden

Occurs when the token is valid but the user lacks required permissions.

HTTP/1.1 403 Forbidden
Content-Type: application/json

{
  "error": {
    "message": "Access denied",
    "code": "forbidden"
  }
}

These shapes match the defaults in our common response configuration and mirror patterns in our controllers (e.g., Mermaid endpoint checks) .

Processing Flow

flowchart LR
  A[Client Request<br/>with Bearer Token]
  A -->|No Token / Invalid| B[401 Unauthorized]
  A -->|Valid Token| C[Permission Check]
  C -->|Insufficient Scopes| D[403 Forbidden]
  C -->|Allowed| E[Controller Execution]

Remediation Steps