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"
}
}
Retry and cancellation
Our system automatically retries failed requests to ensure reliable task completion.
Server-side retry behavior
- Maximum retry attempts: 10 attempts
- Retry condition: Automatic retry on transient failures
The retry process stops when either condition is met:
- 10 retry attempts have been exhausted
- 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.
Client-side retry for server errors
Retry on 500/502 errors: If you receive server errors (500) or bad gateway
errors (502), implement retry logic with exponential backoff. These errors can
occur due to transient issues like temporary network problems or external service
timeouts. While our system retries automatically, implementing client-side retries
provides additional resilience.
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
