Error Handling on AuthOS Docs | Auth Operating System API and SDK Guides

API Error Response Reference

Mon, 01 Jan 0001 00:00:00 +0000

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.

Common API Error Scenarios

Mon, 01 Jan 0001 00:00:00 +0000

Common Error Scenarios

Authentication Errors

Missing Authorization Header

Request:

curl -X GET https://sso.example.com/api/user
# Missing: -H "Authorization: Bearer {jwt}"

Response (401 Unauthorized):

{
  "error": "Missing or invalid Authorization header",
  "error_code": "UNAUTHORIZED",
  "timestamp": "2025-01-15T10:30:00Z"
}

Solution: Include Authorization: Bearer {jwt} header in request.

Expired JWT Token

Request:

curl -X GET https://sso.example.com/api/user \
  -H "Authorization: Bearer {expired_jwt}"

Response (401 Unauthorized):

{
  "error": "Token expired",
  "error_code": "TOKEN_EXPIRED",
  "timestamp": "2025-01-15T10:30:00Z"
}

Solution: Use refresh token to get new access token:

curl -X POST https://sso.example.com/api/auth/refresh \
  -H "Content-Type: application/json" \
  -d '{"refresh_token": "your-refresh-token"}'

Invalid API Key

Request:

API Error Client Patterns

Mon, 01 Jan 0001 00:00:00 +0000

Error Handling Best Practices

1. Check HTTP Status First

Always check the HTTP status code before parsing the response body:

async function makeRequest(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const error = await response.json();
    throw new APIError(response.status, error);
  }

  return response.json();
}

class APIError extends Error {
  constructor(status, errorBody) {
    super(errorBody.error);
    this.status = status;
    this.code = errorBody.error_code;
    this.timestamp = errorBody.timestamp;
  }
}

2. Handle Token Expiration Automatically

Implement automatic token refresh on TOKEN_EXPIRED errors:

async function apiRequestWithRefresh(url, options) {
  let response = await fetch(url, options);

  if (response.status === 401) {
    const error = await response.json();

    if (error.error_code === 'TOKEN_EXPIRED') {
      // Refresh token
      const newTokens = await refreshAccessToken();

      // Retry original request with new token
      options.headers['Authorization'] = `Bearer ${newTokens.access_token}`;
      response = await fetch(url, options);
    }
  }

  return response;
}

3. Implement Exponential Backoff for Rate Limits

Use exponential backoff when encountering rate limits:

API Error Testing and Debugging

Mon, 01 Jan 0001 00:00:00 +0000

Testing Error Scenarios

Unit Testing Error Handling

describe('API Error Handling', () => {
  it('should refresh token on TOKEN_EXPIRED', async () => {
    // Mock expired token response
    fetchMock.mockResponseOnce(
      JSON.stringify({
        error: 'Token expired',
        error_code: 'TOKEN_EXPIRED',
        timestamp: new Date().toISOString()
      }),
      { status: 401 }
    );

    // Mock successful refresh
    fetchMock.mockResponseOnce(
      JSON.stringify({
        access_token: 'new_token',
        refresh_token: 'new_refresh_token'
      })
    );

    // Mock successful retry
    fetchMock.mockResponseOnce(
      JSON.stringify({ id: 'user_123' })
    );

    const result = await apiRequestWithRefresh('/api/user');
    expect(result.id).toBe('user_123');
  });

  it('should handle rate limiting with backoff', async () => {
    // Mock rate limit response
    fetchMock.mockResponseOnce('', {
      status: 429,
      headers: { 'Retry-After': '2' }
    });

    // Mock successful retry
    fetchMock.mockResponseOnce(
      JSON.stringify({ users: [] })
    );

    const result = await fetchWithBackoff('/api/service/users');
    expect(result.users).toEqual([]);
  });
});

Integration Testing

Test error scenarios in integration tests:

API Error Recovery Patterns

Mon, 01 Jan 0001 00:00:00 +0000

Error Recovery Patterns

Automatic Retry with Circuit Breaker

Implement circuit breaker pattern to prevent cascading failures:

class CircuitBreaker {
  constructor(threshold = 5, timeout = 60000) {
    this.failureCount = 0;
    this.threshold = threshold;
    this.timeout = timeout;
    this.state = 'CLOSED'; // CLOSED, OPEN, HALF_OPEN
    this.nextAttempt = Date.now();
  }

  async execute(fn) {
    if (this.state === 'OPEN') {
      if (Date.now() < this.nextAttempt) {
        throw new Error('Circuit breaker is OPEN');
      }
      this.state = 'HALF_OPEN';
    }

    try {
      const result = await fn();
      this.onSuccess();
      return result;
    } catch (error) {
      this.onFailure();
      throw error;
    }
  }

  onSuccess() {
    this.failureCount = 0;
    this.state = 'CLOSED';
  }

  onFailure() {
    this.failureCount++;
    if (this.failureCount >= this.threshold) {
      this.state = 'OPEN';
      this.nextAttempt = Date.now() + this.timeout;
    }
  }
}

const breaker = new CircuitBreaker();

async function makeRequest(url, options) {
  return breaker.execute(() => fetch(url, options));
}

Graceful Degradation

Provide fallback behavior when API is unavailable: