The cloro API uses standard HTTP status codes and consistent error response formats across all endpoints.
HTTP status codes
| Status Code | Meaning | Description |
|---|
200 | Success | Request completed successfully |
400 | Bad Request | Request validation failed |
401 | Unauthorized | Authentication error (missing/invalid API key) |
403 | Forbidden | Insufficient permissions or credits |
404 | Not Found | Endpoint/route not found |
409 | Conflict | Resource conflict |
429 | Too Many Requests | Concurrent request limit exceeded |
499 | Client Closed Request | Request was canceled by client |
500 | Internal Server Error | Server-side error |
502 | Bad Gateway | External service error |
Standard error response
Most errors follow this structure:
{
"error": {
"code": "ERROR_CODE",
"message": "Human-readable error message",
"details": {
// Additional context-specific information
},
"timestamp": "2025-01-15T12:00:00.000Z"
}
}
Validation error (400)
{
"success": false,
"error": "Request validation failed",
"details": [
{
"field": "prompt",
"message": "Prompt cannot be empty"
}
]
}
Canceled request (499)
{
"success": false,
"error": "Request was canceled"
}
Internal error (500)
May return either format:
{
"success": false,
"error": "Maximum retries exceeded"
}
{
"error": {
"code": "INTERNAL_SERVER_ERROR",
"message": "Internal server error",
"timestamp": "2025-01-15T12:00:00.000Z"
}
}
Common error types
Authentication errors (401)
| Error Code | Message | Cause |
|---|
MISSING_API_KEY | Missing or invalid API key | No API key provided in request |
INVALID_API_KEY_FORMAT | Invalid API key format | API key format is incorrect |
INVALID_OR_EXPIRED_API_KEY | Invalid or expired API key | API key is invalid or has expired |
Permission errors (403)
| Error Code | Message | Cause |
|---|
INSUFFICIENT_PERMISSIONS | Insufficient permissions | API key lacks required scopes |
INSUFFICIENT_CREDITS | Insufficient credits | Account has insufficient credits |
Rate Limiting (429)
{
"error": {
"code": "CONCURRENT_LIMIT_EXCEEDED",
"message": "Concurrent limit exceeded",
"details": {
"limit": 10
},
"timestamp": "2025-01-15T12:00:00.000Z"
}
}
External service errors (502)
{
"error": {
"code": "EXTERNAL_SERVICE_ERROR",
"message": "External service error: OpenAI",
"details": {
"service": "OpenAI"
},
"timestamp": "2025-01-15T12:00:00.000Z"
}
}
Request retry logic
For synchronous requests, our system automatically retries failed requests to ensure reliable task completion.
Automatic retry behavior
- Maximum retry attempts: 10 attempts (increased from 5)
- Total timeout duration: 5 minutes
- Retry condition: Automatic retry on transient failures
The retry process stops when any of these conditions are met:
- 10 retry attempts have been exhausted
- 5 minutes have elapsed since the initial request
- The request completes successfully
Client cancellation policy
Requests canceled by clients will be charged: If you cancel a request
after it has been submitted, you will still be charged for the processing that
occurred before cancellation. We charge for the resources consumed, not just
the final result.
Client-side timeout guidance
No client-side timeout needed: Our comprehensive retry mechanism handles
transient failures automatically. You don’t need to implement your own timeout
logic for synchronous requests.
Validation rules
Prompt validation
| Rule | Error Message |
|---|
| Must be 1-10,000 characters | ”Prompt cannot be empty” or “Prompt is too long” |
Country code validation
| Rule | Error Message |
|---|
| Must be valid ISO 3166-1 alpha-2 code | ”Invalid country code” |
Include parameter validation
| Parameter | Valid Values | Error Message |
|---|
include.markdown | true or false | ”Expected boolean” |
include.rawResponse (ChatGPT) | true or false | ”Expected boolean” |
include.searchQueries (ChatGPT) | true or false | ”Expected boolean” |
Troubleshooting
Common issues and solutions
401 Unauthorized
- Check that your API key is included in the Authorization header
- Verify the API key format is correct
- Ensure the API key hasn’t expired
403 Insufficient Credits
- Check your credit balance via response headers
- Top up your account credits
429 Too Many Requests
- Implement proper retry logic with exponential backoff
- Monitor concurrency headers to stay within limits
- Consider queuing requests if you hit limits
400 Validation Errors
- Ensure prompt text is between 1-10,000 characters
- Use valid ISO 3166-1 alpha-2 country codes
- Check that include parameters are boolean values
500/502 Server Errors
- Implement retry logic for transient failures
- Monitor status pages for service availability
- Contact support if errors persist
