Error handling

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

AICPError

import { AICPClient, AICPError } from '@aicp/sdk';

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

Common error types

401type: unauthorizedInvalid or missing API key

402type: plan_upgrade_requiredFeature requires a Cloud plan or above

403type: forbiddenInsufficient role for this operation

404type: not_foundResource does not exist

422type: validation_errorBad request body

429type: rate_limit_exceededToo many requests

502type: provider_errorUpstream provider returned an error

0type: network_errorRequest never reached the server

Handling plan upgrade errors

try {
  await client.projects.create({ name: 'New Project' });
} catch (err) {
  if (err instanceof AICPError && err.status === 402) {
    // Show upgrade prompt
    console.log('Upgrade to Cloud to create projects.');
  }
}

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 AICPError && err.type === '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 })
);