Error Handling

Error formats, status codes, and how to handle failures.

Error Response Format

All errors follow a consistent JSON format:

json

{
  "success": false,
  "error": "Human-readable error message"
}

Queue Task Errors

When a queued task fails, the error is available in the status and result responses:

json

{
  "success": true,
  "data": {
    "queueId": "abc123-def456",
    "status": "error",
    "error": {
      "message": "Model rate limit exceeded",
      "code": "RATE_LIMIT"
    }
  }
}

HTTP Status Codes

Code	Meaning	When
`200`	OK	Request succeeded
`202`	Accepted	Task still processing (poll again)
`400`	Bad Request	Invalid request body or parameters
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions
`404`	Not Found	Queue task or resource not found
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	Server or provider error

Rate Limiting

When rate limits are exceeded, the API returns a 429 response:

json

{
  "success": false,
  "error": "Rate limit exceeded. Try again in 45 seconds."
}

Check the Retry-After header for the number of seconds to wait before retrying.

Handling 202 (Still Processing)

When polling /queue/result and the task isn't done yet:

json

// HTTP 202
{
  "success": false,
  "error": "Task still processing",
  "data": {
    "status": "processing",
    "position": 0
  }
}

Simply retry after a short delay (e.g. 500ms-2s). Use position to estimate wait time.

Finish Reasons

The finishReason field in completion results indicates why the model stopped:

Reason	Description
`stop`	Model completed naturally or hit a stop sequence
`length`	Output hit maxTokens limit — response may be truncated
`content_filter`	Content was filtered by the provider's safety system
`error`	An error occurred during generation

Best Practices

Always check success in the response body
Implement exponential backoff for 429 and 500 errors
Use the Retry-After header when available
Check finishReason for length to detect truncated responses
Use /queue/status to check task state before polling results