API Error Reference

Error Response Format

All API errors follow a consistent format to help with error handling and debugging. Each error response includes an error code, message, and additional context when available.

{
  "error": "ERROR_CODE",
  "message": "Human-readable error message",
  "details": {
    // Additional error context (optional)
  }
}

Common Error Codes

Authentication Errors

• INVALID_CREDENTIALS

  Provided authentication credentials are invalid.

  {
    "error": "INVALID_CREDENTIALS",
    "message": "Invalid username or password",
    "details": {
      "field": "password"
    }
  }

• SESSION_EXPIRED

  The user's session has expired and requires re-authentication.

  {
    "error": "SESSION_EXPIRED",
    "message": "Your session has expired. Please sign in again.",
    "details": {
      "expiredAt": "2025-07-21T22:00:00Z"
    }
  }

Authorization Errors

• UNAUTHORIZED

  User is not authenticated.

  {
    "error": "UNAUTHORIZED",
    "message": "Authentication required to access this resource"
  }

• FORBIDDEN

  User lacks required permissions.

  {
    "error": "FORBIDDEN",
    "message": "Insufficient permissions to perform this action",
    "details": {
      "requiredPermission": "canManageUsers"
    }
  }

Validation Errors

• INVALID_INPUT

  Request contains invalid data.

  {
    "error": "INVALID_INPUT",
    "message": "Invalid request parameters",
    "details": {
      "errors": [
        {
          "field": "email",
          "message": "Invalid email format"
        }
      ]
    }
  }

Server Errors

• INTERNAL_ERROR

  Unexpected server error occurred.

  {
    "error": "INTERNAL_ERROR",
    "message": "An unexpected error occurred",
    "details": {
      "requestId": "req_123abc",
      "timestamp": "2025-07-21T22:15:30Z"
    }
  }

Error Handling Best Practices

• Always check the error code rather than the message for error handling logic
• Implement appropriate retry logic for transient errors
• Log error details for debugging
• Provide user-friendly error messages in your UI

// Example error handling
try {
  await sso.validateSession();
} catch (error) {
  switch (error.code) {
    case 'SESSION_EXPIRED':
      redirectToLogin();
      break;
    case 'FORBIDDEN':
      showPermissionError();
      break;
    default:
      showGenericError();
  }
}