Error Handling

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

Prerequisites

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

Error types

All Auriko errors extend AurikoAPIError. 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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/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 auriko import Client
from auriko.errors import (
    AurikoAPIError,
    APIConnectionError,
    AuthenticationError,
    PermissionDeniedError,
    BadRequestError,
    ConflictError,
    NotFoundError,
    RateLimitError,
    InternalServerError,
    APIStatusError,
)

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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 AurikoAPIError as e:
    print(f"API error ({e.status_code}): {e.message}")

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

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/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 AurikoAPIError) {
        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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1",
)

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

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

import OpenAI from "openai";

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

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

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

import os
from auriko import Client

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

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

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

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

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

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

// Disable retries entirely
const noRetryClient = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/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 auriko import Client
from auriko.errors import RateLimitError, APIStatusError

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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 "@auriko/sdk";

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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 auriko import AsyncClient
from auriko.errors import RateLimitError, APIStatusError

client = AsyncClient(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/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 auriko import Client, AurikoAPIError

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1"
)

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

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

import { Client, AurikoAPIError } from "@auriko/sdk";

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/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 AurikoAPIError) {
            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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/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 auriko import Client
from auriko.errors import APIStatusError

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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 "@auriko/sdk";

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/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 auriko import Client
from auriko.errors import APIConnectionError

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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 "@auriko/sdk";

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/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["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/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.AURIKO_API_KEY,
    baseURL: "https://api.auriko.ai/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 auriko import Client, AurikoAPIError

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

client = Client(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except AurikoAPIError 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, AurikoAPIError } from "@auriko/sdk";

const client = new Client({
    apiKey: process.env.AURIKO_API_KEY,
    baseUrl: "https://api.auriko.ai/v1",
});

try {
    const response = await client.chat.completions.create({
        model: "gpt-4o",
        messages: [{ role: "user", content: "Hello!" }],
    });
} catch (e) {
    if (e instanceof AurikoAPIError) {
        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 Auriko), you can convert OpenAI errors to typed Auriko errors using map_openai_error():

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

client = openai.OpenAI(
    api_key=os.environ["AURIKO_API_KEY"],
    base_url="https://api.auriko.ai/v1"
)

try:
    response = client.chat.completions.create(
        model="gpt-4o",
        messages=[{"role": "user", "content": "Hello!"}]
    )
except openai.APIStatusError as e:
    auriko_error = map_openai_error(e)
    if isinstance(auriko_error, RateLimitError):
        # budget_exhausted and insufficient_quota surface as RateLimitError too;
        # branch on auriko_error.code for code-level retry decisions.
        print(f"Rate limited. Retry after: {auriko_error.retry_after_seconds}s (code={auriko_error.code})")
    elif isinstance(auriko_error, PermissionDeniedError):
        print(f"Permission denied: {auriko_error.message}")
    else:
        raise auriko_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 Auriko SDK directly for typed errors. See OpenAI Compatibility for OpenAI SDK error mapping.

​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