Chuizi.AI
Chuizi.AI

Error Handling

Error Response Formats

OpenAI Protocol (/v1/*)

All errors follow the OpenAI error format:

config.json
json
{
  "error": {
    "message": "Insufficient balance. Current: $0.12, Required: $0.50",
    "type": "insufficient_quota",
    "code": "402"
  }
}

Anthropic Protocol (/anthropic/*)

Errors from the Anthropic protocol use the Anthropic error format:

config.json
json
{
  "type": "error",
  "error": {
    "type": "authentication_error",
    "message": "Invalid API key"
  }
}

Error Code Reference

HTTP StatusError TypeDescriptionRetryable
400invalid_request_errorMalformed request, missing required fields, invalid parameter valuesNo
401authentication_errorInvalid or missing API keyNo
402insufficient_quotaAccount balance too low for the estimated request costNo (top up first)
403permission_errorAPI key does not have permission for this model or actionNo
404not_foundModel does not exist or is not availableNo
429rate_limit_errorToo many requests. Check Retry-After headerYes (after delay)
500server_errorInternal gateway errorYes
502upstream_errorUpstream provider returned an invalid responseYes
503service_unavailableGateway is overloaded or upstream provider is downYes
504timeoutRequest timed out waiting for upstream providerYes

Common Errors and Solutions

401: Authentication Error

config.json
json
{
  "error": {
    "message": "Invalid API key",
    "type": "authentication_error",
    "code": "401"
  }
}

Causes:

  • API key is missing from the request.
  • API key does not start with ck-.
  • API key has been revoked or deactivated.

Fix: Check that your Authorization: Bearer ck-... header is present and the key is active in the dashboard.

402: Insufficient Balance

config.json
json
{
  "error": {
    "message": "Insufficient balance. Current: $0.12",
    "type": "insufficient_quota",
    "code": "402"
  }
}

Fix: Top up your account in the dashboard under Billing. The gateway pre-deducts estimated cost before sending the request upstream. Ensure your balance covers the estimated cost.

429: Rate Limited

config.json
json
{
  "error": {
    "message": "Rate limit exceeded. Retry after 2 seconds.",
    "type": "rate_limit_error",
    "code": "429"
  }
}

Fix: Wait for the duration specified in the Retry-After response header, then retry. Default rate limit is 60 RPM per API key.

504: Timeout

config.json
json
{
  "error": {
    "message": "Request timed out after 120 seconds",
    "type": "timeout",
    "code": "504"
  }
}

Fix: Large models (Opus 4, GPT-5, o3) with long outputs may take over 60 seconds. Set your client timeout to at least 120 seconds. Consider using streaming to get partial results faster.

Tips

  • Log the x-chuizi-generation-id header. Every response includes a generation ID. When reporting issues, include this ID for faster debugging.
  • Use the OpenAI SDK's built-in retry. Both the Python and Node.js OpenAI SDKs have built-in retry logic. Set max_retries when initializing the client.
  • Set client-side timeouts. The default HTTP timeout in many libraries is 30 seconds, which is too short for large model responses. Set it to 120-300 seconds.
  • Monitor 429 rates. If you hit rate limits frequently, contact support to increase your per-key RPM limit, or distribute requests across multiple API keys.

Next Steps