> ## Documentation Index
> Fetch the complete documentation index at: https://docs.samuraiapi.in/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> Every error Samurai AI can return, with causes, fixes, and retry strategies.

## Error Response Format

All errors return a consistent JSON structure:

```json theme={null}
{
  "error": {
    "type": "rate_limit_exceeded",
    "message": "Daily request limit reached for closed-source models. Resets at midnight UTC.",
    "code": 429
  }
}
```

## Complete Error Reference

| HTTP  | Type                   | Cause                                                           | Fix                                                                             |
| ----- | ---------------------- | --------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `400` | `bad_request`          | Malformed JSON, invalid parameters, unsupported param for model | Check request body against the [API reference](/api-reference/introduction)     |
| `401` | `auth_error`           | Missing, invalid, or revoked API key                            | Verify your `Authorization: Bearer sk-samurai-...` header                       |
| `402` | `insufficient_credits` | PAYG credit balance is \$0.00                                   | Add credits at [dashboard/billing](https://www.samuraiapi.in/dashboard/billing) |
| `403` | `permission_denied`    | Model requires a higher plan tier                               | Check [pricing plans](/reference/pricing) and upgrade                           |
| `404` | `not_found`            | Model ID doesn't exist or is unavailable                        | Check [models list](/reference/models) for valid IDs                            |
| `422` | `validation_error`     | Parameter values failed validation (e.g. temperature > 2)       | Check parameter ranges in the docs                                              |
| `429` | `rate_limit_exceeded`  | Daily request limit hit for your plan                           | Wait until midnight UTC or upgrade plan                                         |
| `500` | `server_error`         | Internal server error                                           | Retry with exponential backoff                                                  |
| `503` | `model_unavailable`    | Upstream provider (OpenAI, Anthropic, etc.) is down             | Try a fallback model or retry                                                   |

***

## Common Errors & Solutions

<AccordionGroup>
  <Accordion title="401 — Invalid API Key">
    **Symptoms:** Every request fails immediately with `auth_error`

    **Causes & Fixes:**

    * Key starts with `sk-samurai-` but was revoked → Create a new key in the [dashboard](https://www.samuraiapi.in/dashboard)
    * Passing `OPENAI_API_KEY` instead of your Samurai key → Use `SAMURAI_API_KEY`
    * Extra spaces or newlines in the key → Strip whitespace with `.strip()`
    * Header format wrong → Must be `Authorization: Bearer sk-samurai-YOUR_KEY`

    ```python theme={null}
    import os
    key = os.environ.get("SAMURAI_API_KEY", "").strip()
    # Verify it looks right
    assert key.startswith("sk-samurai-"), f"Bad key format: {key[:20]}..."
    ```
  </Accordion>

  <Accordion title="402 — Insufficient Credits">
    **Symptoms:** Requests to Pro models (o1, Sora, DALL-E 3 HD) fail with `insufficient_credits`

    **Fix:**

    1. Go to [Dashboard → Billing](https://www.samuraiapi.in/dashboard/billing)
    2. Purchase PAYG credits (\$5 minimum)
    3. Credits are applied instantly

    **Note:** Subscription plans (Free/Starter/Pro) give request quotas. PAYG credits are separate and needed for Pro-tier models.
  </Accordion>

  <Accordion title="403 — Permission Denied">
    **Symptoms:** Request works for some models but not others

    **Cause:** Your current plan doesn't include that model class.

    | Model Class                            | Minimum Plan       |
    | -------------------------------------- | ------------------ |
    | Open-source (Llama, Mistral, DeepSeek) | Free               |
    | Closed-source (GPT-4o, Claude, Gemini) | Free (limited)     |
    | Pro (o1, Sora, DALL-E 3 HD)            | Pro + PAYG credits |

    **Fix:** Upgrade at [Dashboard → Billing](https://www.samuraiapi.in/dashboard/billing)
  </Accordion>

  <Accordion title="429 — Rate Limit Exceeded">
    **Symptoms:** Requests fail mid-session, especially for high-volume use

    **Plan limits (requests per day):**

    | Plan    | Open-source | Closed-source | Pro |
    | ------- | ----------- | ------------- | --- |
    | Free    | 150         | 70            | 0   |
    | Starter | 2,000       | 1,000         | 0   |
    | Pro     | 4,500       | 2,500         | 650 |

    **Fix:** Implement exponential backoff (see below) or upgrade your plan.
  </Accordion>

  <Accordion title="503 — Model Unavailable">
    **Symptoms:** Specific model fails but others work fine

    **Cause:** The upstream provider (OpenAI, Anthropic, Google) is experiencing an outage.

    **Fix:** Use a fallback model:

    ```python theme={null}
    FALLBACKS = {
        "gpt-4o": "claude-3-5-sonnet-20241022",
        "claude-3-5-sonnet-20241022": "gemini-2.0-flash",
        "gemini-2.0-flash": "deepseek-chat",
    }
    ```
  </Accordion>
</AccordionGroup>

***

## Retry with Exponential Backoff

```python theme={null}
import time
import random
from openai import OpenAI, RateLimitError, APIStatusError

client = OpenAI(
    api_key="sk-samurai-YOUR_KEY",
    base_url="https://www.samuraiapi.in/v1"
)

def chat_with_retry(messages: list, model: str = "gpt-4o", max_retries: int = 5):
    """Chat with automatic retry on rate limits and server errors."""
    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages
            )
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            wait = (2 ** attempt) + random.uniform(0, 1)
            print(f"Rate limited. Retrying in {wait:.1f}s (attempt {attempt + 1}/{max_retries})")
            time.sleep(wait)
        except APIStatusError as e:
            if e.status_code >= 500 and attempt < max_retries - 1:
                wait = (2 ** attempt) + random.uniform(0, 1)
                print(f"Server error {e.status_code}. Retrying in {wait:.1f}s")
                time.sleep(wait)
            else:
                raise
```

## Model Fallback Pattern

```python theme={null}
FALLBACK_CHAIN = [
    "gpt-4o",
    "claude-3-5-sonnet-20241022",
    "gemini-2.0-flash",
    "deepseek-chat",  # cheapest fallback
]

def chat_with_fallback(messages: list):
    for model in FALLBACK_CHAIN:
        try:
            return client.chat.completions.create(
                model=model,
                messages=messages
            )
        except Exception as e:
            print(f"Model {model} failed: {e}. Trying next...")
    raise RuntimeError("All models failed")
```

## Node.js Error Handling

```typescript theme={null}
import OpenAI, { APIError, RateLimitError, AuthenticationError } from 'openai';

const client = new OpenAI({
  apiKey: process.env.SAMURAI_API_KEY,
  baseURL: 'https://www.samuraiapi.in/v1'
});

try {
  const response = await client.chat.completions.create({
    model: 'gpt-4o',
    messages: [{ role: 'user', content: 'Hello!' }]
  });
  console.log(response.choices[0].message.content);
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key — check your SAMURAI_API_KEY env var');
  } else if (error instanceof RateLimitError) {
    console.error('Rate limited — implement backoff or upgrade plan');
  } else if (error instanceof APIError) {
    console.error(`API error ${error.status}: ${error.message}`);
  } else {
    throw error;
  }
}
```

***

## Error Response Format

All errors return a consistent JSON structure:

```json theme={null}
{
  "error": {
    "type": "auth_error",
    "message": "Invalid API key provided.",
    "code": 401
  }
}
```

## Error Code Reference

| HTTP Status | Type                   | Cause                        | Solution                       |
| ----------- | ---------------------- | ---------------------------- | ------------------------------ |
| `400`       | `bad_request`          | Invalid request parameters   | Check your request body        |
| `401`       | `auth_error`           | Missing or invalid API key   | Verify your API key            |
| `402`       | `insufficient_credits` | PAYG credit balance depleted | Add credits in dashboard       |
| `403`       | `permission_denied`    | Model requires higher plan   | Upgrade your plan              |
| `404`       | `not_found`            | Model ID doesn't exist       | Check `/reference/models`      |
| `422`       | `validation_error`     | Request failed validation    | Check parameter types          |
| `429`       | `rate_limit_exceeded`  | Daily request limit hit      | Wait until midnight UTC        |
| `500`       | `server_error`         | Internal server error        | Retry with backoff             |
| `503`       | `model_unavailable`    | Upstream provider is down    | Try again or use another model |

## Common Errors & Fixes

<AccordionGroup>
  <Accordion title="401 - Invalid API Key">
    **Problem:** Your API key is missing, malformed, or revoked.

    **Fix:** Check that:

    * You're passing `Authorization: Bearer sk-samurai-YOUR_KEY`
    * The key hasn't been deleted from your dashboard
    * There are no leading/trailing spaces in your key
  </Accordion>

  <Accordion title="403 - Permission Denied">
    **Problem:** The model requires a higher subscription plan.

    **Fix:** Check which plan includes your target model at [/reference/pricing](/reference/pricing). Upgrade from your dashboard.
  </Accordion>

  <Accordion title="402 - Insufficient Credits">
    **Problem:** Your PAYG credit balance is \$0.

    **Fix:** Add credits from [Dashboard → Billing](https://www.samuraiapi.in/dashboard/billing). Pro models require PAYG credits on top of your subscription.
  </Accordion>

  <Accordion title="429 - Rate Limit Exceeded">
    **Problem:** You've hit your daily request limit.

    **Fix:** Wait until midnight UTC for the limit to reset, implement request queuing, or upgrade your plan.
  </Accordion>

  <Accordion title="503 - Model Unavailable">
    **Problem:** The upstream provider (OpenAI, Anthropic, etc.) is experiencing downtime.

    **Fix:** Implement fallback to another model:

    ```python theme={null}
    primary_model = "claude-3-5-sonnet-20241022"
    fallback_model = "gpt-4o"

    try:
        response = client.chat.completions.create(model=primary_model, messages=messages)
    except Exception:
        response = client.chat.completions.create(model=fallback_model, messages=messages)
    ```
  </Accordion>
</AccordionGroup>

## Python Error Handling

```python theme={null}
from openai import (
    AuthenticationError,
    RateLimitError,
    APIStatusError,
    APIConnectionError
)

try:
    response = client.chat.completions.create(model="gpt-4o", messages=messages)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError:
    print("Rate limit hit — wait and retry")
except APIStatusError as e:
    print(f"API error {e.status_code}: {e.message}")
except APIConnectionError:
    print("Network error — check your connection")
```