API Errors
Comprehensive guide to handling errors in the UltraReach.ai API, including error codes, troubleshooting steps, and best practices for error handling.
Error Response Format
{
"error": {
"type": "validation_error",
"code": "INVALID_PARAMETER",
"message": "The provided parameter is invalid",
"details": {
"field": "email",
"reason": "invalid_format"
},
"request_id": "req_123456789"
}
}Common Error Types
Issues with API keys or access tokens
Invalid input parameters or formats
Too many requests in a time period
Internal system issues or downtime
HTTP Status Codes
4xx Client Errors
The request was malformed or invalid
Missing or invalid authentication
Valid auth but insufficient permissions
The requested resource doesn't exist
Rate limit has been exceeded
5xx Server Errors
Unexpected server error occurred
Invalid response from upstream server
Server is temporarily unavailable
Upstream server request timeout
Error Handling Best Practices
- •Always check error responses
- •Implement retry logic with backoff
- •Log errors with request IDs
- •Handle rate limits gracefully
Retry Strategy
const retry = async (fn, maxAttempts = 3) => {
for (let i = 0; i < maxAttempts; i++) {
try {
return await fn();
} catch (error) {
if (!isRetryable(error) ||
i === maxAttempts - 1) {
throw error;
}
await wait(Math.pow(2, i) * 1000);
}
}
};Rate Limiting Headers
Total requests allowed
Requests remaining
Time until limit resets
Error Resolution Guide
Authentication
Check API keys and token validity
Validation
Verify request parameters and formats
Rate Limits
Implement request throttling
Server Issues
Check system status and retry later