Error Handling

Every error response includes a machine-readable code, a canonical type, and the request_id for support correlation.

Prerequisites

An Arbytra API key
Python 3.10+ with the OpenAI SDK (pip install openai) or the arbytra SDK (pip install arbytra)
- OR Node.js 18+ with the OpenAI SDK (npm install openai) or @arbytra/sdk (npm install @arbytra/sdk)

Error types

All Arbytra errors extend ArbytraAPIError. The envelope is canonical (see Errors):

Field	Type	Description
`message`	`str`	Human-readable error message
`status_code`	`int`	HTTP status code
`code`	`str`	Machine-readable error code
`type`	`str`	Canonical error type (one of six values)
`param`	`str \| None`	Parameter that caused the error
`request_id` / `requestId`	`str`	Value of `x-request-id` on the failing response
`retry_after_seconds` / `retryAfterSeconds`	`int \| None`	`Retry-After` header value (429 / 503 only)
`doc_url` / `docUrl`	`str \| None`	Link to the error’s docs page
`provider`	`str \| None`	Upstream provider that generated the error, when attributable

The SDK provides these typed exception classes:

Exception	HTTP	`type`
`BadRequestError`	400 / 413 / 422	`invalid_request_error`
`AuthenticationError`	401	`authentication_error`
`PermissionDeniedError`	403	`permission_error`
`NotFoundError`	404	`not_found_error`
`ConflictError`	409	`invalid_request_error`
`RateLimitError`	429	`rate_limit_error`
`InternalServerError`	500	`api_error`
`APIStatusError`	502 / 503 / 504	`api_error`
`APIConnectionError`	—	network failure before any response

Dispatch on type + HTTP status for exception class, then on code for precise handling within a class. Never branch on message text; see Errors for retry policy by code.

See the Python SDK Reference or TypeScript SDK Reference for complete error class fields and hierarchy.

Handle errors

Catch typed exceptions:

import os
import openai

client = openai.OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
    print(response.choices[0].message.content)

except openai.AuthenticationError as e:
    print(f"Check your API key (status={e.status_code})")
except openai.RateLimitError as e:
    print(f"Rate limited (status={e.status_code})")
except openai.NotFoundError as e:
    print(f"Not found: {e.message}")
except openai.BadRequestError as e:
    print(f"Bad request: {e.message}")
except openai.PermissionDeniedError as e:
    print(f"Not allowed: {e.message}")
except openai.InternalServerError as e:
    print(f"Server error (status={e.status_code})")
except openai.APIStatusError as e:
    print(f"API error ({e.status_code}): {e.message}")
except openai.APIConnectionError as e:
    print(f"Network error: {e}")

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/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 (e) {
    if (e instanceof OpenAI.AuthenticationError) {
        console.log(`Check your API key (status=${e.status})`);
    } else if (e instanceof OpenAI.RateLimitError) {
        console.log(`Rate limited (status=${e.status})`);
    } else if (e instanceof OpenAI.NotFoundError) {
        console.log(`Not found: ${e.message}`);
    } else if (e instanceof OpenAI.BadRequestError) {
        console.log(`Bad request: ${e.message}`);
    } else if (e instanceof OpenAI.PermissionDeniedError) {
        console.log(`Not allowed: ${e.message}`);
    } else if (e instanceof OpenAI.InternalServerError) {
        console.log(`Server error (status=${e.status})`);
    } else if (e instanceof OpenAI.APIConnectionError) {
        console.log(`Network error: ${e.message}`);
    } else if (e instanceof OpenAI.APIError) {
        console.log(`API error (${e.status}): ${e.message}`);
    }
}

import os
from arbytra import Client
from arbytra.errors import (
    ArbytraAPIError,
    APIConnectionError,
    AuthenticationError,
    PermissionDeniedError,
    BadRequestError,
    ConflictError,
    NotFoundError,
    RateLimitError,
    InternalServerError,
    APIStatusError,
)

client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
    print(response.choices[0].message.content)

except AuthenticationError as e:
    print(f"Check your API key (request_id={e.request_id})")

except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after_seconds}s")

except NotFoundError as e:
    print(f"Not found: {e.message} (param={e.param})")

except BadRequestError as e:
    print(f"Bad request: {e.message} (param={e.param})")

except PermissionDeniedError as e:
    print(f"Not allowed: {e.message} (code={e.code})")

except ConflictError as e:
    print(f"Conflict: {e.message} (code={e.code})")

except InternalServerError as e:
    print(f"Server error (request_id={e.request_id})")

except APIStatusError as e:
    print(f"Upstream error ({e.status_code}): {e.message}")

except APIConnectionError as e:
    print(f"Network error: {e.message}")

except ArbytraAPIError as e:
    print(f"API error ({e.status_code}): {e.message}")

import {
    Client,
    ArbytraAPIError,
    APIConnectionError,
    AuthenticationError,
    PermissionDeniedError,
    BadRequestError,
    ConflictError,
    NotFoundError,
    RateLimitError,
    InternalServerError,
    APIStatusError,
} from "@arbytra/sdk";

const client = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/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 (e) {
    if (e instanceof AuthenticationError) {
        console.log(`Check your API key (requestId=${e.requestId})`);
    } else if (e instanceof RateLimitError) {
        console.log(`Rate limited, retry after ${e.retryAfterSeconds}s`);
    } else if (e instanceof NotFoundError) {
        console.log(`Not found: ${e.message} (param=${e.param})`);
    } else if (e instanceof BadRequestError) {
        console.log(`Bad request: ${e.message} (param=${e.param})`);
    } else if (e instanceof PermissionDeniedError) {
        console.log(`Not allowed: ${e.message} (code=${e.code})`);
    } else if (e instanceof ConflictError) {
        console.log(`Conflict: ${e.message} (code=${e.code})`);
    } else if (e instanceof InternalServerError) {
        console.log(`Server error (requestId=${e.requestId})`);
    } else if (e instanceof APIStatusError) {
        console.log(`Upstream error (${e.statusCode}): ${e.message}`);
    } else if (e instanceof APIConnectionError) {
        console.log(`Network error: ${e.message}`);
    } else if (e instanceof ArbytraAPIError) {
        console.log(`API error (${e.statusCode}): ${e.message}`);
    }
}

Use built-in retries

The SDK automatically retries transient errors with exponential backoff:

Setting	Value
Max retries	2 (default)
Initial interval	500ms
Max interval	30 seconds
Backoff	Exponential (1.5 exponent) + random jitter
Retried status codes	429, 500, 502, 503, 504
Connection/timeout errors	Retried
`Retry-After` header	Respected (overrides backoff when present)

import os
from openai import OpenAI

# Default: 2 retries with exponential backoff
client = OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
)

# More retries
client = OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=5,
)

# Disable retries
client = OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=0,
)

import OpenAI from "openai";

// Default: 2 retries with exponential backoff
const client = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
});

// More retries
const resilientClient = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
    maxRetries: 5,
});

// Disable retries
const noRetryClient = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
    maxRetries: 0,
});

import os
from arbytra import Client

# Default: 2 retries with exponential backoff
client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1"
)

# More retries for resilience
client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=5
)

# Disable retries entirely
client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=0
)

import { Client } from "@arbytra/sdk";

// Default: 2 retries with exponential backoff
const client = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
});

// More retries for resilience
const resilientClient = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
    maxRetries: 5,
});

// Disable retries entirely
const noRetryClient = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
    maxRetries: 0,
});

When the server returns a Retry-After header (common with 429 responses), the SDK uses that value instead of the calculated backoff interval.

Retry manually

For request-level control over backoff or error filtering, implement custom retry logic:

import os
import time
import openai

client = openai.OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=0,
)

def make_request_with_retry(messages, max_retries=3):
    last_error = None

    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages,
            )
        except openai.RateLimitError as e:
            last_error = e
            retry_after = e.response.headers.get("Retry-After")
            wait_time = float(retry_after) if retry_after else min(2 ** attempt, 60)
            time.sleep(wait_time)

        except openai.APIStatusError as e:
            last_error = e
            retry_after = e.response.headers.get("Retry-After")
            wait_time = float(retry_after) if retry_after else 2 ** attempt
            time.sleep(wait_time)

    raise last_error

# Usage
response = make_request_with_retry([{"role": "user", "content": "Hello!"}])

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
    maxRetries: 0,
});

async function makeRequestWithRetry(
    messages: Array<{ role: string; content: string }>,
    maxRetries = 3
) {
    let lastError: Error | undefined;

    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await client.chat.completions.create({
                model: "gpt-4o",
                messages,
            });
        } catch (e) {
            lastError = e as Error;
            if (e instanceof OpenAI.RateLimitError || e instanceof OpenAI.APIError) {
                const retryAfter = (e as OpenAI.APIError).headers?.["retry-after"];
                const waitMs = (retryAfter ? parseFloat(retryAfter) : Math.min(2 ** attempt, 60)) * 1000;
                await new Promise((r) => setTimeout(r, waitMs));
            } else {
                throw e;
            }
        }
    }

    throw lastError;
}

import os
import time
from arbytra import Client
from arbytra.errors import RateLimitError, APIStatusError

client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=0  # Disable auto-retry
)

def make_request_with_retry(messages, max_retries=3):
    last_error = None

    for attempt in range(max_retries):
        try:
            return client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except RateLimitError as e:
            last_error = e
            wait_time = e.retry_after_seconds or min(2 ** attempt, 60)
            time.sleep(wait_time)

        except APIStatusError as e:
            last_error = e
            wait_time = e.retry_after_seconds or 2 ** attempt
            time.sleep(wait_time)

    raise last_error

# Usage
response = make_request_with_retry([{"role": "user", "content": "Hello!"}])

import { Client, RateLimitError, APIStatusError } from "@arbytra/sdk";

const client = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
    maxRetries: 0, // Disable auto-retry
});

async function makeRequestWithRetry(
    messages: Array<{ role: string; content: string }>,
    maxRetries = 3
) {
    let lastError: Error | undefined;

    for (let attempt = 0; attempt < maxRetries; attempt++) {
        try {
            return await client.chat.completions.create({
                model: "gpt-4o",
                messages,
            });
        } catch (e) {
            lastError = e as Error;
            if (e instanceof RateLimitError || e instanceof APIStatusError) {
                const waitMs = (e.retryAfterSeconds ?? Math.min(2 ** attempt, 60)) * 1000;
                await new Promise((r) => setTimeout(r, waitMs));
            } else {
                throw e;
            }
        }
    }

    throw lastError;
}

Retry asynchronously

Retry with async/await:

import os
import asyncio
import openai

client = openai.AsyncOpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=0,
)

async def make_request_with_backoff(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await client.chat.completions.create(
                model="gpt-4o",
                messages=messages,
            )
        except (openai.RateLimitError, openai.APIStatusError) as e:
            if attempt == max_retries - 1:
                raise
            retry_after = e.response.headers.get("Retry-After")
            wait_time = float(retry_after) if retry_after else 2 ** attempt
            await asyncio.sleep(wait_time)

import os
import asyncio
from arbytra import AsyncClient
from arbytra.errors import RateLimitError, APIStatusError

client = AsyncClient(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    max_retries=0
)

async def make_request_with_backoff(messages, max_retries=3):
    for attempt in range(max_retries):
        try:
            return await client.chat.completions.create(
                model="gpt-4o",
                messages=messages
            )
        except (RateLimitError, APIStatusError) as e:
            if attempt == max_retries - 1:
                raise
            wait_time = e.retry_after_seconds or 2 ** attempt
            await asyncio.sleep(wait_time)

TypeScript is inherently async. See the TypeScript tabs in Retry manually.

Side effects and retries: When using tools or multi-step workflows, consider whether retries are safe. A retried request that triggers a tool call may execute the tool twice. For idempotency-sensitive operations, either disable automatic retries (max_retries=0) or implement your own deduplication logic.

Fall back to another model

Catch the error from your primary model and retry with a different one:

import os
import openai

client = openai.OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
)

def chat_with_fallback(messages):
    try:
        return client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            extra_body={"gateway": {"routing": {"max_ttft_ms": 1000}}},
        )
    except openai.APIError as e:
        print(f"Primary failed ({e}), trying fallback...")

        return client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages,
        )

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
});

async function chatWithFallback(messages: any[]) {
    try {
        return await client.chat.completions.create({
            model: "gpt-4o",
            messages,
            gateway: { routing: { max_ttft_ms: 1000 } },
        });
    } catch (e) {
        if (e instanceof OpenAI.APIError) {
            console.log(`Primary failed (${e}), trying fallback...`);
            return await client.chat.completions.create({
                model: "gpt-4o-mini",
                messages,
            });
        }
        throw e;
    }
}

import os
from arbytra import Client, ArbytraAPIError

client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1"
)

def chat_with_fallback(messages):
    try:
        return client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
            gateway={"routing": {"max_ttft_ms": 1000}}
        )
    except ArbytraAPIError as e:
        print(f"Primary failed ({e}), trying fallback...")

        return client.chat.completions.create(
            model="gpt-4o-mini",
            messages=messages
        )

import { Client, ArbytraAPIError } from "@arbytra/sdk";

const client = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
});

async function chatWithFallback(messages: any[]) {
    try {
        return await client.chat.completions.create({
            model: "gpt-4o",
            messages,
            gateway: { routing: { max_ttft_ms: 1000 } },
        });
    } catch (e) {
        if (e instanceof ArbytraAPIError) {
            console.log(`Primary failed (${e}), trying fallback...`);
            return await client.chat.completions.create({
                model: "gpt-4o-mini",
                messages,
            });
        }
        throw e;
    }
}

Use circuit breakers

A circuit breaker stops sending requests after repeated failures and re-tests after a timeout:

import os
from datetime import datetime, timedelta, timezone
import openai

client = openai.OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
)

class CircuitBreaker:
    def __init__(self, failure_threshold=5, reset_timeout=60):
        self.failures = 0
        self.failure_threshold = failure_threshold
        self.reset_timeout = reset_timeout
        self.last_failure = None
        self.is_open = False

    def record_failure(self):
        self.failures += 1
        self.last_failure = datetime.now(timezone.utc)
        if self.failures >= self.failure_threshold:
            self.is_open = True

    def record_success(self):
        self.failures = 0
        self.is_open = False

    def can_proceed(self):
        if not self.is_open:
            return True
        if datetime.now(timezone.utc) - self.last_failure > timedelta(seconds=self.reset_timeout):
            self.is_open = False
            return True
        return False

# Usage
breaker = CircuitBreaker()

def safe_request(messages):
    if not breaker.can_proceed():
        raise Exception("Circuit breaker open, try later")

    try:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=messages,
        )
        breaker.record_success()
        return response
    except openai.APIStatusError as e:
        breaker.record_failure()
        raise

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
});

class CircuitBreaker {
    private failures = 0;
    private lastFailure: Date | null = null;
    private isOpen = false;

    constructor(
        private failureThreshold = 5,
        private resetTimeout = 60_000,
    ) {}

    recordFailure() {
        this.failures++;
        this.lastFailure = new Date();
        if (this.failures >= this.failureThreshold) this.isOpen = true;
    }

    recordSuccess() {
        this.failures = 0;
        this.isOpen = false;
    }

    canProceed(): boolean {
        if (!this.isOpen) return true;
        if (Date.now() - this.lastFailure!.getTime() > this.resetTimeout) {
            this.isOpen = false;
            return true;
        }
        return false;
    }
}

const breaker = new CircuitBreaker();

async function safeRequest(messages: any[]) {
    if (!breaker.canProceed()) throw new Error("Circuit breaker open, try later");

    try {
        const response = await client.chat.completions.create({ model: "gpt-4o", messages });
        breaker.recordSuccess();
        return response;
    } catch (e) {
        if (e instanceof OpenAI.APIError && !(e instanceof OpenAI.APIConnectionError)) {
            breaker.recordFailure();
        }
        throw e;
    }
}

import os
from datetime import datetime, timedelta, timezone
from arbytra import Client
from arbytra.errors import APIStatusError

client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1"
)

class CircuitBreaker:
    def __init__(self, failure_threshold=5, reset_timeout=60):
        self.failures = 0
        self.failure_threshold = failure_threshold
        self.reset_timeout = reset_timeout
        self.last_failure = None
        self.is_open = False

    def record_failure(self):
        self.failures += 1
        self.last_failure = datetime.now(timezone.utc)
        if self.failures >= self.failure_threshold:
            self.is_open = True

    def record_success(self):
        self.failures = 0
        self.is_open = False

    def can_proceed(self):
        if not self.is_open:
            return True
        if datetime.now(timezone.utc) - self.last_failure > timedelta(seconds=self.reset_timeout):
            self.is_open = False
            return True
        return False

# Usage
breaker = CircuitBreaker()

def safe_request(messages):
    if not breaker.can_proceed():
        raise Exception("Circuit breaker open, try later")

    try:
        response = client.chat.completions.create(
            model="gpt-4o",
            messages=messages
        )
        breaker.record_success()
        return response
    except APIStatusError as e:
        breaker.record_failure()
        raise

import { Client, APIStatusError } from "@arbytra/sdk";

const client = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
});

class CircuitBreaker {
    private failures = 0;
    private lastFailure: Date | null = null;
    private isOpen = false;

    constructor(
        private failureThreshold = 5,
        private resetTimeout = 60_000,
    ) {}

    recordFailure() {
        this.failures++;
        this.lastFailure = new Date();
        if (this.failures >= this.failureThreshold) this.isOpen = true;
    }

    recordSuccess() {
        this.failures = 0;
        this.isOpen = false;
    }

    canProceed(): boolean {
        if (!this.isOpen) return true;
        if (Date.now() - this.lastFailure!.getTime() > this.resetTimeout) {
            this.isOpen = false;
            return true;
        }
        return false;
    }
}

const breaker = new CircuitBreaker();

async function safeRequest(messages: any[]) {
    if (!breaker.canProceed()) throw new Error("Circuit breaker open, try later");

    try {
        const response = await client.chat.completions.create({ model: "gpt-4o", messages });
        breaker.recordSuccess();
        return response;
    } catch (e) {
        if (e instanceof APIStatusError) breaker.recordFailure();
        throw e;
    }
}

Set timeouts

import os
import openai

client = openai.OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    timeout=30.0,
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Write a long essay..."}],
    )
except openai.APIConnectionError as e:
    print(f"Connection failed: {e}")

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
    timeout: 30000,
});

try {
    const response = await client.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Write a long essay..." }],
    });
} catch (e) {
    if (e instanceof OpenAI.APIConnectionError) {
        console.log(`Connection failed: ${e.message}`);
    }
}

import os
from arbytra import Client
from arbytra.errors import APIConnectionError

client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
    timeout=30.0  # 30 second timeout
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Write a long essay..."}]
    )
except APIConnectionError as e:
    print(f"Connection failed: {e.message}")

import { Client, APIConnectionError } from "@arbytra/sdk";

const client = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
    timeout: 30000, // 30 second timeout (ms)
});

try {
    const response = await client.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Write a long essay..." }],
    });
} catch (e) {
    if (e instanceof APIConnectionError) {
        console.log(`Connection failed: ${e.message}`);
    }
}

Log errors

Log errors for debugging:

import os
import logging
import openai

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = openai.OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1",
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except openai.APIStatusError as e:
    logger.exception("Chat completion failed", extra={
        "error_type": type(e).__name__,
        "status_code": e.status_code,
        "request_id": e.response.headers.get("x-request-id"),
        "model": "gpt-4o",
    })
    raise

import OpenAI from "openai";

const client = new OpenAI({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseURL: "https://api.arbytra.com/v1",
});

try {
    const response = await client.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Hello!" }],
    });
} catch (e) {
    if (e instanceof OpenAI.APIError) {
        console.error("Chat completion failed", {
            error_type: e.constructor.name,
            status_code: e.status,
            request_id: e.request_id,
            model: "gpt-4o",
        });
    }
    throw e;
}

import os
import logging
from arbytra import Client, ArbytraAPIError

logging.basicConfig(level=logging.INFO)
logger = logging.getLogger(__name__)

client = Client(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except ArbytraAPIError as e:
    logger.exception("Chat completion failed", extra={
        "error_type": type(e).__name__,
        "status_code": e.status_code,
        "request_id": e.request_id,
        "model": "gpt-4o",
    })
    raise

import { Client, ArbytraAPIError } from "@arbytra/sdk";

const client = new Client({
    apiKey: process.env.ARBYTRA_API_KEY,
    baseUrl: "https://api.arbytra.com/v1",
});

try {
    const response = await client.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Hello!" }],
    });
} catch (e) {
    if (e instanceof ArbytraAPIError) {
        console.error("Chat completion failed", {
            error_type: e.constructor.name,
            status_code: e.statusCode,
            request_id: e.requestId,
            model: "gpt-4o",
        });
    }
    throw e;
}

Map OpenAI SDK errors

If you use the OpenAI SDK directly (with base_url pointed at Arbytra), you can convert OpenAI errors to typed Arbytra errors using map_openai_error():

import os
import openai
from arbytra import map_openai_error
from arbytra.errors import RateLimitError, PermissionDeniedError

client = openai.OpenAI(
    api_key=os.environ["ARBYTRA_API_KEY"],
    base_url="https://api.arbytra.com/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except openai.APIStatusError as e:
    arbytra_error = map_openai_error(e)
    if isinstance(arbytra_error, RateLimitError):
        # budget_exhausted and insufficient_quota surface as RateLimitError too;
        # branch on arbytra_error.code for code-level retry decisions.
        print(f"Rate limited. Retry after: {arbytra_error.retry_after_seconds}s (code={arbytra_error.code})")
    elif isinstance(arbytra_error, PermissionDeniedError):
        print(f"Permission denied: {arbytra_error.message}")
    else:
        raise arbytra_error

You get typed error fields (status_code, code, response_headers) and fine-grained isinstance checks, even when using the OpenAI client. map_openai_error() is Python-only. TypeScript users should use the Arbytra SDK directly for typed errors. See OpenAI Compatibility for OpenAI SDK error mapping.

Get Started

Guides

Response API

Frameworks

Integrations

Specifications

Platform

Changelog

Prerequisites

Error types

Handle errors

Use built-in retries

Retry manually

Retry asynchronously

Fall back to another model

Use circuit breakers

Set timeouts

Log errors

Map OpenAI SDK errors

​Prerequisites

​Error types

​Handle errors

​Use built-in retries

​Retry manually

​Retry asynchronously

​Fall back to another model

​Use circuit breakers

​Set timeouts

​Log errors

​Map OpenAI SDK errors

Prerequisites

Error types

Handle errors

Use built-in retries

Retry manually

Retry asynchronously

Fall back to another model

Use circuit breakers

Set timeouts

Log errors

Map OpenAI SDK errors