Errors

HTTP status codes, error formats, and troubleshooting guide

llm.kiwi uses standard HTTP response codes and returns detailed error objects for easy debugging.

HTTP Status Codes

Code	Type	Description
200	Success	Request completed successfully.
400	Bad Request	Invalid parameters or malformed request.
401	Unauthorized	Missing or invalid API key.
403	Forbidden	Key lacks required permissions or tier access.
404	Not Found	Resource or endpoint doesn’t exist.
429	Rate Limited	Too many requests. Slow down and retry.
500	Server Error	Internal error. Retry with backoff.
503	Service Unavailable	Temporary outage. Retry shortly.

Error Response Format

{
  "error": {
    "message": "The model 'invalid-model' does not exist.",
    "type": "invalid_request_error",
    "code": "model_not_found",
    "param": "model"
  }
}

Field	Description
message	Human-readable error description.
type	Error category (e.g., invalid_request_error, rate_limit_error).
code	Machine-readable error code for handling.
param	The specific parameter that caused the error (if applicable).

Common Errors & Solutions

401: Invalid API Key

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

Solutions:

• Verify your key is correct and hasn’t been rotated
• Ensure the Authorization header is formatted as Bearer YOUR_API_KEY
• Check that your key is active in the Dashboard

429: Rate Limit Exceeded

{"error": {"message": "Rate limit exceeded", "type": "rate_limit_error"}}

Solutions:

• Implement exponential backoff (see below)
• Check X-RateLimit-Reset header for when limits reset
• Consider upgrading to a higher tier

400: Context Length Exceeded

{"error": {"message": "Context length exceeded", "type": "invalid_request_error", "code": "context_length_exceeded"}}

Solutions:

• Reduce the length of your prompt or conversation history
• Decrease max_tokens parameter
• Use a model with higher context limits

403: Insufficient Tier

{"error": {"message": "This feature requires Pro tier", "type": "access_denied_error"}}

Solutions:

• Upgrade your account at llm.kiwi/pricing
• Use a feature available on your current tier

Retry Strategy

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

Python

import time
import random

def retry_with_backoff(func, max_retries=5):
    for attempt in range(max_retries):
        try:
            return func()
        except Exception as e:
            if not is_retryable(e) or attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            time.sleep(wait)

def is_retryable(error):
    return getattr(error, 'status_code', 0) in [429, 500, 503]

Always check the X-RateLimit-* headers to proactively avoid hitting limits.