Error handling

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

NuRouteError

import { NuRouteClient, NuRouteError } from '@aicp/sdk';

try {
  await client.chat.complete({ model: 'auto', messages: [] });
} catch (err) {
  if (err instanceof NuRouteError) {
    console.error(err.status);    // HTTP status code (0 for network errors)
    console.error(err.message);   // human-readable message
    console.error(err.errorType);      // error type string
    console.error(err.code);      // machine-readable code or null
  }
}

Common error types

400errorType: 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

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

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

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

403errorType: 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

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

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

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

422errorType: invalid_request_errorChat request body that fails validation

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

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

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

502errorType: provider_errorUpstream provider returned an error

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

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

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

0errorType: network_errorRequest never reached the server

Handling 402 errors

A 402 has two causes: your organization's prepaid credits are used up, or the project's hard-limited monthly budget is spent. errorType tells them apart:

try {
  await client.chat.complete({ model: 'auto', messages });
} catch (err) {
  if (err instanceof NuRouteError && err.status === 402) {
    if (err.errorType === 'insufficient_credits') console.log('Top up your credits on the Billing page.');
    if (err.errorType === 'budget_exceeded') console.log("Raise the project's budget, or wait for next month (UTC).");
  }
}

Retry on network errors

async function withRetry<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
  for (let i = 0; i < retries; i++) {
    try {
      return await fn();
    } catch (err) {
      if (err instanceof NuRouteError && err.errorType === 'network_error' && i < retries - 1) {
        await new Promise(r => setTimeout(r, 2 ** i * 500));
        continue;
      }
      throw err;
    }
  }
  throw new Error('unreachable');
}

const response = await withRetry(() =>
  client.chat.complete({ model: 'auto', messages })
);