Errors

The Developer API uses standard HTTP response codes and returns error details in a consistent JSON format.

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "error": "Error message describing what went wrong"
}

HTTP Status Codes

400 Bad Request

The request was malformed or invalid.

{
  "success": false,
  "error": "Invalid company UUID"
}

Common causes:

• Invalid UUID format
• Missing required parameters
• Invalid parameter types or values

401 Unauthorized

Authentication failed or API key is invalid.

{
  "success": false,
  "error": "Invalid API key."
}

Common causes:

• Missing API key
• Invalid API key format
• API key not found
• API key is disabled
• API key hash mismatch

403 Forbidden

The request is valid but access is denied.

{
  "success": false,
  "error": "Developer API add-on required."
}

Common causes:

• Developer API add-on not active
• IP restriction violation
• Usage limit exceeded

Usage Limit Exceeded:

{
  "success": false,
  "error": "Monthly usage limit reached. Usage resets on the first of next month."
}

404 Not Found

The requested resource doesn't exist.

{
  "success": false,
  "error": "Company not found"
}

Common causes:

• Resource UUID doesn't exist
• Resource belongs to different company
• Resource was deleted

500 Internal Server Error

An unexpected error occurred on the server.

{
  "success": false,
  "error": "An error occurred"
}

If you encounter this error, please contact support with:

• The endpoint you were calling
• The request ID (if provided in response headers)
• The approximate time of the request

Error Handling Best Practices

1. Check status codes: Always check the HTTP status code, not just the response body
2. Handle 401/403: These indicate authentication/authorization issues — verify your API key and subscription
3. Retry logic: Implement exponential backoff for 500 errors
4. Idempotency: Use Idempotency-Key header for safe retries on network errors
5. Log errors: Log error responses for debugging and monitoring

Usage Limit Errors

When you exceed your monthly usage limit:

• Status: 403 Forbidden
• Error message: "Monthly usage limit reached. Usage resets on the first of next month."
• Response headers: Still include X-Usage-Count, X-Usage-Limit, X-Usage-Resets

The request is still logged but not processed. Usage resets automatically on the first day of the next month.

Response Headers

All error responses include standard headers:

• X-Usage-Count: Current month's request count (even for errors)
• X-Usage-Limit: Your monthly limit
• X-Usage-Resets: ISO timestamp when usage resets

If an Idempotency-Key header was provided:

• X-Idempotency-Key: Echo of the provided key
• X-Idempotency-Cached: "true" if cached response returned, "false" if new request processed