Error Handling

Overview

The Semaphor API uses standard HTTP status codes and provides detailed error information to help you understand and resolve issues. All error responses follow a consistent format and are common across the Dashboards, Visuals, and Tokens APIs.

Error Response Format

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

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "Additional error context",
      "suggestion": "Suggested solution"
    }
  }
}

HTTP Status Codes

Common Error Codes

Authentication & Token Errors (All APIs)

Dashboards API Errors

Visuals API Errors

Security Policy Errors (Dashboards & Visuals)

Validation Errors (All APIs)

Error Handling Examples

See the Tokens API, Dashboards API, and Visuals API for endpoint-specific error examples and how to handle them in your code.

JavaScript/TypeScript

async function handleApiRequest(url: string, options: RequestInit) {
  try {
    const response = await fetch(url, options);
    if (!response.ok) {
      const errorData = await response.json();
      // ...handle errors as shown in the docs
    }
    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

Best Practices

• Always check the error.code and error.message fields in error responses.
• Implement retry logic for rate limiting and server errors.
• Log errors and monitor for recurring issues.
• Validate all request parameters and payloads before sending.
• Reference the Tokens API, Dashboards API, and Visuals API for more details on error handling in context.