Error handling

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 or rate limit exceeded (depends on endpoint type)
`499`	Client Closed Request	Request was canceled by client
`500`	Internal Server Error	Server-side error
`502`	Bad Gateway	External 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": {
    "code": "REQUEST_CANCELED",
    "message": "Request was canceled by client",
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

You will be charged for canceled requests: If you receive a 499 status code, your account is still charged for the processing that occurred before cancellation. We charge for resources consumed, not just completed results.

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)

Concurrency limit exceeded (monitor endpoints /v1/monitor/*):

{
  "error": {
    "code": "CONCURRENT_LIMIT_EXCEEDED",
    "message": "Concurrent limit exceeded",
    "details": {
      "limit": 10
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Rate limit exceeded (all endpoints /v1/*):

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit": 1000,
      "window": "1s"
    },
    "timestamp": "2025-01-15T12:00:00.000Z"
  }
}

Batch endpoint errorsThe batch task creation endpoint uses a partial success model. Individual tasks can fail with per-task error codes (VALIDATION_ERROR, RESOURCE_ALREADY_EXISTS, INSUFFICIENT_CREDITS) inside a 200 response. See the batch endpoint documentation for details.

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 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 because of transient issues like temporary network problems or external service timeouts. Our system retries automatically, and client-side retries add another layer of 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 a valid uppercase ISO 3166-1 alpha-2 code (e.g., `"US"`, `"GB"`) — lowercase values are not accepted	”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 For all endpoints:

Monitor rate limit headers (X-RateLimit-Remaining) to avoid hitting the 1,000/sec per-endpoint limit
Implement request throttling to stay within the rate limit
The counter resets every second, so brief delays can help avoid rate limit errors

For monitor endpoints (additional limits):

Monitor concurrency headers to stay within your plan’s concurrent request limit
Implement proper retry logic with exponential backoff
Consider queuing requests if you hit concurrency 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

Common questions

Why are some of my requests failing with 500 errors?

500 errors indicate server-side issues. Here’s what they typically mean and how to handle them:

Provider issues: the upstream AI provider is experiencing problems.
Invalid request format: your request doesn’t match the API specification.
Temporary infrastructure issues: brief service disruptions or maintenance.

Best practice for production: Always implement retry logic with exponential backoff. Our system retries failed requests automatically (up to 10 attempts), and client-side retries add another layer of resilience for 5xx errors.

Where do I see logs for successful requests?

Every monitor request — sync and async — is logged to the dashboard with the request id, provider, prompt, country, status code, credits charged, and latency. Successful (2xx) requests show up alongside failures so you can audit usage end-to-end. Entries typically appear within a minute; if a request seems missing, refresh — heavy load occasionally delays ingestion but does not drop entries.

Is there a bulk export of request logs?

No. The dashboard shows logs in a paginated view only — there is no CSV export or bulk download. For log analysis at scale, log the X-Request-ID response header on every API call alongside your own metadata at the point of call. This gives you a permanent audit trail keyed to cloro’s internal request IDs for support lookups.

Can I read the request latency from the API response?

No. The latency value shown in the dashboard logs is measured server-side and is not returned in the API response body or in a response header. To capture per-request timing on your side, measure the wall-clock duration around your HTTP call and correlate the result back to the dashboard entry using the X-Request-Id response header.

An async task returned `200 OK` but the result looks wrong. What does that mean?

200 OK from GET /v1/async/task/{taskId} only confirms the task record exists. The task’s outcome lives inside task.status — see task states for the full lifecycle and the COMPLETED vs. upstream-error FAQ for how to detect degraded provider responses.

What’s the expected success rate for API requests?

Our average success rate is >99% across all providers. However, several factors can affect success rates:

Provider stability: Upstream AI provider reliability varies by provider
Geographic region: Some regions may have different success rates depending on infrastructure
Time of day: Peak usage times may affect performance

Introduction

Guides

Integrations

Error handling

HTTP status codes

Error response formats

Standard error response

Validation error (400)

Canceled request (499)

Internal error (500)

Common error types

Authentication errors (401)

Permission errors (403)

Rate Limiting (429)

External service errors (502)

Retry and cancellation

Server-side retry behavior

Client cancellation policy

Client-side timeout guidance

Client-side retry for server errors

Validation rules

Prompt validation

Country code validation

Include parameter validation

Troubleshooting

Common issues and solutions

Common questions

Why are some of my requests failing with 500 errors?

Where do I see logs for successful requests?

Is there a bulk export of request logs?

Can I read the request latency from the API response?

An async task returned `200 OK` but the result looks wrong. What does that mean?

What’s the expected success rate for API requests?

​HTTP status codes

​Error response formats

​Standard error response

​Validation error (400)

​Canceled request (499)

​Internal error (500)

​Common error types

​Authentication errors (401)

​Permission errors (403)

​Rate Limiting (429)

​External service errors (502)

​Retry and cancellation

​Server-side retry behavior

​Client cancellation policy

​Client-side timeout guidance

​Client-side retry for server errors

​Validation rules

​Prompt validation

​Country code validation

​Include parameter validation

​Troubleshooting

​Common issues and solutions

​Common questions

​Why are some of my requests failing with 500 errors?

​Where do I see logs for successful requests?

​Is there a bulk export of request logs?

​Can I read the request latency from the API response?

​An async task returned 200 OK but the result looks wrong. What does that mean?

​What’s the expected success rate for API requests?

HTTP status codes

Error response formats

Standard error response

Validation error (400)

Canceled request (499)

Internal error (500)

Common error types

Authentication errors (401)

Permission errors (403)

Rate Limiting (429)

External service errors (502)

Retry and cancellation

Server-side retry behavior

Client cancellation policy

Client-side timeout guidance

Client-side retry for server errors

Validation rules

Prompt validation

Country code validation

Include parameter validation

Troubleshooting

Common issues and solutions

Common questions

Why are some of my requests failing with 500 errors?

Where do I see logs for successful requests?

Is there a bulk export of request logs?

Can I read the request latency from the API response?

An async task returned `200 OK` but the result looks wrong. What does that mean?

What’s the expected success rate for API requests?