Error Handling

Overview

The Claude Code Proxy API returns standard HTTP status codes and structured error responses for different types of failures.

HTTP Status Codes

• 200 - Success
• 400 - Bad Request (invalid parameters)
• 401 - Unauthorized (invalid or missing authentication)
• 403 - Forbidden (insufficient permissions)
• 404 - Not Found (invalid endpoint)
• 429 - Too Many Requests (rate limit exceeded)
• 500 - Internal Server Error
• 503 - Service Unavailable (Claude API unavailable)

Error Response Format

All errors return a JSON response with the following structure:

{
  "error": {
    "type": "invalid_request_error",
    "message": "The request was invalid",
    "code": "invalid_parameter"
  }
}

Common Error Types

Authentication Errors

{
  "error": {
    "type": "authentication_error",
    "message": "Invalid bearer token",
    "code": "invalid_token"
  }
}

Rate Limit Errors

{
  "error": {
    "type": "rate_limit_error",
    "message": "Too many requests",
    "code": "rate_limit_exceeded"
  }
}

Invalid Request Errors

{
  "error": {
    "type": "invalid_request_error",
    "message": "Missing required parameter: messages",
    "code": "missing_parameter"
  }
}

Best Practices

1. Always check HTTP status codes
2. Handle rate limiting with exponential backoff
3. Parse error responses for detailed information
4. Log errors for debugging
5. Implement proper retry logic