Error handling

All SDK methods raise NuRouteError on non-2xx responses or network failures.

NuRouteError

from nuroute import NuRouteClient
from nuroute.errors import NuRouteError

client = NuRouteClient(api_key="aicp-...", base_url="https://your-gateway")

try:
    response = client.chat.complete(
        model="auto",
        messages=[{"role": "user", "content": "Hello!"}],
    )
except NuRouteError as e:
    print(e.status)      # HTTP status code (0 for network errors)
    print(str(e))        # human-readable message
    print(e.error_type)  # error type string
    print(e.code)        # machine-readable code or None

Common error types

400error_type: invalid_request_errorInvalid header or parameter, e.g. model auto-apollo-tier or auto-v1 (no longer available; send auto), an x-nuroute-router other than artemis or v2, or a max_tokens over the project's limit

401error_type: invalid_request_errorMissing, invalid or expired API key or session token

402error_type: insufficient_creditsCredit balance used up; top up to continue

402error_type: budget_exceededThe project's hard-limited monthly budget is spent

403error_type: forbiddenInsufficient role (changing settings needs an owner's or admin's session; an API key has no role), an endpoint closed to project-scoped API keys, or a project header naming another project

403error_type: policy_violationThe request names a model or provider the project's policy rules out

403error_type: email_not_verifiedChat requests need a verified email address in your organization

404error_type: not_foundResource does not exist, or is outside a project-scoped key's project

422error_type: invalid_request_errorChat request body that fails validation

422error_type: no_available_modelNothing your rules or the project's policy and provider connections allow can serve the request, e.g. with fallbackBehavior fail

429error_type: too_many_concurrent_requestsYour organization has the most requests running at once that it may

429error_type: provider_errorEvery provider that could serve the request is rate-limited or unavailable

502error_type: provider_errorUpstream provider returned an error

503error_type: routing_errorRouting unavailable, or a hard-limited project's spend could not be read; retry shortly

503error_type: billing_unavailableYour credit balance could not be checked; retry shortly

503error_type: pii_redaction_unavailablePII redaction is required (fail closed) but unavailable

0error_type: network_errorRequest never reached the server

Retry on network errors

import time
from nuroute.errors import NuRouteError

def with_retry(fn, retries=3):
    for attempt in range(retries):
        try:
            return fn()
        except NuRouteError as e:
            if e.error_type == "network_error" and attempt < retries - 1:
                time.sleep(2 ** attempt * 0.5)
                continue
            raise

response = with_retry(lambda: client.chat.complete(
    model="auto",
    messages=[{"role": "user", "content": "Hello!"}],
))

Async retry

import asyncio
from nuroute.errors import NuRouteError

async def with_retry_async(fn, retries=3):
    for attempt in range(retries):
        try:
            return await fn()
        except NuRouteError as e:
            if e.error_type == "network_error" and attempt < retries - 1:
                await asyncio.sleep(2 ** attempt * 0.5)
                continue
            raise