Error Handling

Learn how to handle API errors and implement proper error recovery.

Error Response Format

All API errors follow a consistent format:

Field	Type	Description
`code`	string	Machine-readable error code
`message`	string	Human-readable error message
`status`	integer	HTTP status code
`details`	object	Additional error context (optional)
`requestId`	string	Unique request ID for debugging

Status	Meaning	Common Causes
`200`	OK	Request successful
`201`	Created	Resource created successfully
`400`	Bad Request	Invalid parameters, malformed JSON
`401`	Unauthorized	Invalid or missing API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Resource doesn't exist
`409`	Conflict	Resource already exists
`422`	Unprocessable	Validation errors
`429`	Too Many Requests	Rate limit exceeded
`500`	Server Error	Internal server error
`503`	Service Unavailable	Temporary maintenance

Code	Description
`invalid_api_key`	The API key is invalid or malformed
`expired_api_key`	The API key has been revoked
`missing_api_key`	No API key was provided
`insufficient_permissions`	Key doesn't have access to this resource
`ip_not_allowed`	Request from unauthorized IP address

Code	Description
`invalid_request`	Request body is malformed
`missing_required_field`	A required field is missing
`invalid_field_value`	A field has an invalid value
`invalid_url`	URL is malformed or not HTTPS
`invalid_flow_type`	Flow type must be "standard" or "enhanced"
`payload_too_large`	Request body exceeds 10MB limit
`image_too_large`	Image file exceeds 10MB limit. Compress or resize before uploading.
`suspicious_content`	Request blocked due to suspicious patterns in submitted text
`invalid_webhook_url`	Webhook URL must be HTTPS and not point to internal/private IPs

Code	Description
`resource_not_found`	The requested resource doesn't exist
`verification_not_found`	Verification with given ID not found
`link_not_found`	Verification link not found
`link_expired`	Verification link has expired
`link_already_used`	Verification link was already used
`webhook_exists`	Webhook with this URL already exists

Code	Description
`rate_limit_exceeded`	Too many requests
`verification_limit_exceeded`	Monthly verification quota reached

Validation errors include detailed field-level information:

Implement exponential backoff for retryable errors:

Every API response includes a unique requestId. Include this when contacting support: