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)
| Status | Code | Description |
|---|---|---|
| 401 | MISSING_API_KEY | The x-api-key header was not provided |
| 401 | INVALID_API_KEY | The API key is invalid, revoked, or expired |
| 403 | INSUFFICIENT_SCOPE | The API key does not have permission for this operation |
| 403 | IP_NOT_ALLOWED | The request IP is not in the API key’s allowlist |
Validation Errors (400)
| Code | Description |
|---|---|
VALIDATION_ERROR | The request body failed validation. Check the message for details. |
MISSING_COMPANY_ID | A required company identifier is missing |
Resource Errors (404)
| Code | Description |
|---|---|
NOT_FOUND | The requested resource does not exist or is not accessible |
Rate Limiting (429)
| Code | Description |
|---|---|
RATE_LIMIT_EXCEEDED | Too many requests. Check RateLimit-Reset header for retry timing. |
Server Errors (5xx)
| Status | Code | Description |
|---|---|---|
| 503 | SERVICE_UNAVAILABLE | The 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}`);
}
}