Error Codes

Error Response Format

All errors return a consistent JSON structure:

{
  "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
`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
`403`	`permission_denied`	Model requires a higher plan tier	Check pricing plans and upgrade
`404`	`not_found`	Model ID doesn’t exist or is unavailable	Check models list 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

401 — Invalid API Key

Symptoms: Every request fails immediately with auth_errorCauses & Fixes:

Key starts with sk-samurai- but was revoked → Create a new key in the 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

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]}..."

402 — Insufficient Credits

Symptoms: Requests to Pro models (o1, Sora, DALL-E 3 HD) fail with insufficient_creditsFix:

Go to Dashboard → Billing
Purchase PAYG credits ($5 minimum)
Credits are applied instantly

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

403 — Permission Denied

Symptoms: Request works for some models but not othersCause: 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

429 — Rate Limit Exceeded

Symptoms: Requests fail mid-session, especially for high-volume usePlan 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.

503 — Model Unavailable

Symptoms: Specific model fails but others work fineCause: The upstream provider (OpenAI, Anthropic, Google) is experiencing an outage.Fix: Use a fallback model:

FALLBACKS = {
    "gpt-4o": "claude-3-5-sonnet-20241022",
    "claude-3-5-sonnet-20241022": "gemini-2.0-flash",
    "gemini-2.0-flash": "deepseek-chat",
}

Retry with Exponential Backoff

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

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

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:

{
  "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

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

403 - Permission Denied

Problem: The model requires a higher subscription plan.Fix: Check which plan includes your target model at /reference/pricing. Upgrade from your dashboard.

402 - Insufficient Credits

Problem: Your PAYG credit balance is $0.Fix: Add credits from Dashboard → Billing. Pro models require PAYG credits on top of your subscription.

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.

503 - Model Unavailable

Problem: The upstream provider (OpenAI, Anthropic, etc.) is experiencing downtime.Fix: Implement fallback to another model:

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)

Python Error Handling

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")

Get Started

Chat & Text

Image Generation

Video Generation

Audio

SDKs & Libraries

Reference

Error Response Format

Complete Error Reference

Common Errors & Solutions

Retry with Exponential Backoff

Model Fallback Pattern

Node.js Error Handling

Error Response Format

Error Code Reference

Common Errors & Fixes

Python Error Handling

Get Started

Chat & Text

Image Generation

Video Generation

Audio

SDKs & Libraries

Reference

​Error Response Format

​Complete Error Reference

​Common Errors & Solutions

​Retry with Exponential Backoff

​Model Fallback Pattern

​Node.js Error Handling

​Error Response Format

​Error Code Reference

​Common Errors & Fixes

​Python Error Handling

Error Response Format

Complete Error Reference

Common Errors & Solutions

Retry with Exponential Backoff

Model Fallback Pattern

Node.js Error Handling

Error Response Format

Error Code Reference

Common Errors & Fixes

Python Error Handling