Skip to main content

​
Error Response Format

All errors follow a consistent format: 
{
  "error": {
    "code": "ERROR_CODE",
    "message": "A human-readable description of the error"
  }
}

​
Error Codes

​
Authentication Errors (4xx)

StatusCodeDescription
401MISSING_API_KEYThe x-api-key header was not provided
401INVALID_API_KEYThe API key is invalid, revoked, or expired
403INSUFFICIENT_SCOPEThe API key does not have permission for this operation

​
Validation Errors (400)

CodeDescription
VALIDATION_ERRORThe request body failed validation. Check the message for details.
MISSING_COMPANY_IDA required company identifier is missing

​
Resource Errors (404)

CodeDescription
NOT_FOUNDThe requested resource does not exist or is not accessible

​
Rate Limiting (429)

CodeDescription
RATE_LIMIT_EXCEEDEDToo many requests. Check RateLimit-Reset header for retry timing.

​
Server Errors (5xx)

StatusCodeDescription
503SERVICE_UNAVAILABLEThe service is temporarily unavailable. Retry with backoff.

​
Handling Errors

const response = await fetch(url, {
  headers: { 'x-api-key': apiKey }
});

if (!response.ok) {
  const body = await response.json();
  const { code, message } = body.error;

  switch (code) {
    case 'INVALID_API_KEY':
      // Re-authenticate or check key
      break;
    case 'RATE_LIMIT_EXCEEDED':
      // Wait and retry
      break;
    case 'VALIDATION_ERROR':
      // Fix request body
      break;
    default:
      // Log and handle unexpected errors
      console.error(`API error: ${code} - ${message}`);
  }
}