Skip to main content

Error Codes

Reference for all error codes returned by the Korad.AI API.

Error Response Format​

All errors follow this format:

{
  "error": {
    "type": "error_type",
    "message": "Human-readable error message"
  }
}

HTTP Status Codes​

400 Bad Request​

{
  "error": {
    "type": "invalid_request_error",
    "message": "Invalid request body"
  }
}

Causes:

  • Malformed JSON
  • Invalid parameter values
  • Missing required fields

401 Unauthorized​

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

Causes:

  • Missing or invalid API key
  • Expired key
  • Revoked key

Solution: Verify your API key is correct and active.

403 Forbidden​

{
  "error": {
    "type": "permission_error",
    "message": "Insufficient permissions"
  }
}

Causes:

  • API key lacks required scope
  • Rate limit exceeded
  • Feature not available on your plan

404 Not Found​

{
  "error": {
    "type": "invalid_request_error",
    "message": "Resource not found"
  }
}

Causes:

  • Invalid endpoint
  • Non-existent model
  • Invalid message ID

429 Rate Limit Exceeded​

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded. Please try again later."
  }
}

Headers included:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1706720400

Causes:

  • Too many requests
  • Token limit exceeded

500 Internal Server Error​

{
  "error": {
    "type": "api_error",
    "message": "An internal error occurred"
  }
}

Causes:

  • Server-side error
  • Upstream API failure

502 Bad Gateway​

{
  "error": {
    "type": "upstream_error",
    "message": "Upstream API error"
  }
}

Causes:

  • Anthropic API is down
  • Network issue with upstream

503 Service Unavailable​

{
  "error": {
    "type": "overloaded_error",
    "message": "Service temporarily unavailable"
  }
}

Causes:

  • Server overload
  • Maintenance mode

Error Types​

Authentication Errors​

TypeDescription
authentication_errorInvalid or missing API key

Request Errors​

TypeDescription
invalid_request_errorMalformed request or invalid parameters
validation_errorRequest validation failed

Rate Limit Errors​

TypeDescription
rate_limit_errorRate limit exceeded

Server Errors​

TypeDescription
api_errorInternal server error
upstream_errorUpstream API failure
overloaded_errorService overloaded

Handling Errors​

Python​

from anthropic import AnthropicError, APITimeoutError

try:
    response = client.messages.create(...)
except AnthropicError as e:
    if e.status_code == 401:
        print("Invalid API key")
    elif e.status_code == 429:
        print("Rate limit exceeded - retry later")
    elif e.status_code >= 500:
        print("Server error - please try again")
    else:
        print(f"Error: {e.message}")
except APITimeoutError:
    print("Request timed out")

JavaScript​

try {
  const response = await client.messages.create(...);
} catch (error) {
  if (error.status === 401) {
    console.log('Invalid API key');
  } else if (error.status === 429) {
    console.log('Rate limit exceeded');
  } else if (error.status >= 500) {
    console.log('Server error');
  }
}

cURL​

response=$(curl -s -w "\n%{http_code}" https://api.korad.ai/v1/messages ...)
http_code=$(tail -n1 <<< "$response")

if [ $http_code -eq 401 ]; then
  echo "Invalid API key"
elif [ $http_code -eq 429 ]; then
  echo "Rate limit exceeded"
fi

Retry Strategy​

For transient errors (500, 502, 503), implement exponential backoff:

import time

def create_with_retry(client, **kwargs):
  max_retries = 3
  base_delay = 1  # seconds

  for attempt in range(max_retries):
    try:
      return client.messages.create(**kwargs)
    except AnthropicError as e:
      if e.status_code >= 500 and attempt < max_retries - 1:
        delay = base_delay * (2 ** attempt)
        print(f"Server error, retrying in {delay}s...")
        time.sleep(delay)
      else:
        raise

  raise Exception("Max retries exceeded")

Best Practices​

  1. Always check error type — Different errors need different handling
  2. Implement retry logic — For 5xx errors with exponential backoff
  3. Monitor rate limits — Check X-RateLimit-* headers
  4. Log errors — Keep track of errors for debugging
  5. Handle timeouts — Set appropriate timeout values

API Overview → Chat Completions →