Skip to main content
The cloro API uses standard HTTP status codes and consistent error response formats across all endpoints.

HTTP status codes

Status CodeMeaningDescription
200SuccessRequest completed successfully
400Bad RequestRequest validation failed
401UnauthorizedAuthentication error (missing/invalid API key)
403ForbiddenInsufficient permissions or credits
404Not FoundEndpoint/route not found
409ConflictResource conflict
429Too Many RequestsConcurrent request limit exceeded
499Client Closed RequestRequest was canceled by client
500Internal Server ErrorServer-side error
502Bad GatewayExternal service error

Error response formats

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"
}
or
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Internal server error",
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Common error types

Authentication errors (401)

Error CodeMessageCause
MISSING_API_KEYMissing or invalid API keyNo API key provided in request
INVALID_API_KEY_FORMATInvalid API key formatAPI key format is incorrect
INVALID_OR_EXPIRED_API_KEYInvalid or expired API keyAPI key is invalid or has expired

Permission errors (403)

Error CodeMessageCause
INSUFFICIENT_PERMISSIONSInsufficient permissionsAPI key lacks required scopes
INSUFFICIENT_CREDITSInsufficient creditsAccount 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"
  }
}

Validation rules

Prompt validation

RuleError Message
Must be 1-10,000 characters”Prompt cannot be empty” or “Prompt is too long”

Country code validation

RuleError Message
Must be valid ISO 3166-1 alpha-2 code”Invalid country code”

Include parameter validation

ParameterValid ValuesError Message
include.markdowntrue 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