Auriko uses standard HTTP status codes and returns detailed error information in the response body.
All errors follow this format:
{
"error": {
"message": "Human-readable error message",
"type": "error_type",
"code": "error_code",
"param": "optional_parameter_name"
}
}
HTTP status codes
| Status | Description |
|---|
| 400 | Bad Request — Invalid parameters or missing required fields |
| 401 | Unauthorized — Invalid API key or BYOK provider key |
| 402 | Payment Required — Insufficient credits or budget exceeded |
| 403 | Forbidden — Insufficient permissions for this action |
| 404 | Not Found — Model not in catalog |
| 429 | Too Many Requests — Rate limit exceeded |
| 500 | Internal Server Error — Unexpected Auriko error |
| 502 | Bad Gateway — Upstream provider error |
| 503 | Service Unavailable — No providers available or service down |
| 504 | Gateway Timeout — Upstream provider timeout |
Error codes
Authentication (401)
| Code | Description |
|---|
invalid_api_key | The API key is invalid or missing |
provider_auth_error | BYOK key authentication failed at the upstream provider |
provider_auth_error means your own provider key (BYOK) was rejected. This is distinct from invalid_api_key, which means your Auriko API key is invalid.
Request errors (400)
| Code | Description |
|---|
invalid_request | The request body is malformed or a parameter has an invalid value |
missing_required_parameter | A required parameter is missing |
param field in the error response identifies the offending field (for example, messages or routing.only_byok).
Billing errors (402)
| Code | Description |
|---|
insufficient_quota | Account has insufficient credits |
budget_exceeded | Budget limit hit (workspace, key, or BYOK scope) |
Authorization (403)
| Code | Description |
|---|
forbidden | You don’t have permission for this action |
Not found (404)
| Code | Description |
|---|
model_not_found | The specified model is not in the catalog |
Rate limiting (429)
| Code | Description |
|---|
rate_limit_exceeded | Too many requests — back off and retry |
Server errors (500)
| Code | Description |
|---|
internal_error | An unexpected error occurred on Auriko’s side |
Provider errors (502, 503, 504)
| Code | Status | Description |
|---|
provider_error | 502 | Upstream provider returned an error |
provider_error | 504 | Upstream provider timed out |
no_providers_available | 503 | No providers can serve this model/request |
service_unavailable | 503 | Auriko service temporarily unavailable |
Retry guidance
| Status | Retryable | Recommended action |
|---|
| 400 | No | Fix the request parameters |
401 (invalid_api_key) | No | Check your Auriko API key |
401 (provider_auth_error) | No | Check your BYOK provider key |
| 402 | No | Add credits or raise budget limit |
| 403 | No | Check permissions or use session authentication |
| 404 | No | Use a valid model name (see Models) |
| 429 | Yes | Back off using Retry-After header or exponential backoff |
| 500 | Yes | Retry with backoff |
| 502 | Yes | Retry — different provider may be selected |
| 503 | Yes | Retry with backoff |
| 504 | Yes | Retry — upstream provider timed out |
Provider error mapping
When an upstream provider returns an error, Auriko maps it to a client-facing response:
| Upstream condition | Client status | Client code |
|---|
| 504 timeout | 504 | provider_error |
| Other 5xx | 502 | provider_error |
| 401 auth failure | 401 | provider_auth_error |
| 429 rate limit | 429 | rate_limit_exceeded |
| 400 bad request | 400 | invalid_request |
| Other 4xx | 502 | provider_error |
Handle SDK errors
import os
from auriko import (
Client,
AurikoAPIError,
AuthenticationError,
RateLimitError,
BudgetExceededError,
ModelNotFoundError,
ProviderError,
# Also available: InvalidRequestError, InsufficientCreditsError,
# InternalError, ProviderAuthError, ServiceUnavailableError
)
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 AuthenticationError as e:
print(f"Check your API key: {e}")
except RateLimitError as e:
print(f"Rate limited, retry later: {e}")
except BudgetExceededError as e:
print(f"Budget exceeded: {e}")
except ModelNotFoundError as e:
print(f"Model not found: {e}")
except ProviderError as e:
print(f"Provider error: {e}")
except AurikoAPIError as e:
# Catches all other Auriko errors
print(f"API error ({e.status_code}): {e}")
Retry logic
For transient errors (429, 500, 502, 503, 504), the SDK includes built-in retries with exponential backoff. See the Error Handling guide for retry configuration and custom retry patterns.
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"
)
# Disable retries for manual control
client = Client(
api_key=os.environ["AURIKO_API_KEY"],
base_url="https://api.auriko.ai/v1",
max_retries=0
)
The Auriko SDK includes built-in retry logic with configurable max_retries parameter. The SDK respects Retry-After headers when present.
