Skip to main content

​
Error Handling

How to handle API errors.

​
Error Response Format

All errors follow this format: 
{
  "error": {
    "code": "error_code",
    "message": "Human-readable message",
    "details": { }
  }
}

​
HTTP Status Codes

CodeMeaning
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Valid key but insufficient permissions
404Not Found - Resource doesn’t exist
422Unprocessable - Valid request but can’t be processed
429Rate Limited - Too many requests
500Server Error - Something went wrong on our end

​
Common Error Codes

​
Authentication Errors

CodeDescription
invalid_api_keyAPI key is invalid
missing_api_keyNo API key provided
expired_api_keyAPI key has been revoked
insufficient_permissionsKey doesn’t have required permissions

​
Validation Errors

CodeDescription
invalid_parameterA parameter is invalid
missing_parameterA required parameter is missing
invalid_jsonRequest body is not valid JSON

​
Resource Errors

CodeDescription
not_foundResource doesn’t exist
already_existsResource already exists
conflictResource state conflict

​
Rate Limit Errors

CodeDescription
rate_limit_exceededToo many requests

​
Error Details

Some errors include additional details: 
{
  "error": {
    "code": "invalid_parameter",
    "message": "Invalid parameter: level",
    "details": {
      "parameter": "level",
      "value": "invalid",
      "allowed": ["debug", "info", "warn", "error", "fatal"]
    }
  }
}

​
Handling Errors

​
Ruby Example

response = HTTP.post(url, json: data)

case response.status
when 200..299
  JSON.parse(response.body)["data"]
when 400
  error = JSON.parse(response.body)["error"]
  raise ValidationError, error["message"]
when 401
  raise AuthenticationError, "Invalid API key"
when 429
  retry_after = response.headers["Retry-After"].to_i
  sleep(retry_after)
  retry
when 500..599
  raise ServerError, "API server error"
end

​
JavaScript Example

try {
  const response = await fetch(url, { method: 'POST', body: data });

  if (!response.ok) {
    const error = await response.json();
    throw new Error(error.error.message);
  }

  return await response.json();
} catch (e) {
  console.error('API Error:', e.message);
}

​
Retry Strategy

ErrorRetry?Strategy
400NoFix the request
401NoCheck API key
403NoCheck permissions
404NoCheck resource exists
429YesWait for Retry-After
500YesExponential backoff
502YesExponential backoff
503YesExponential backoff

​
Request IDs

Every response includes a request ID: 
{
  "meta": {
    "request_id": "req_abc123def456"
  }
}
Include this when contacting support.