Error handling

📘What it really is

• Things that will go wrong, and what to do:
• rate limits (429): you've sent too many requests; wait and retry (the response says how long);
• overloaded or server errors (5xx, 529): temporary; retry with exponential backoff (wait 1s, 2s, 4s...) and a limit;
• timeouts and network errors: retry a limited number of times;
• bad requests (400), authentication (401), permission (403): your mistake or configuration; don't retry, fix it and log it;
• hit max_tokens: the answer was cut off (stop_reason: "max_tokens"); raise the limit or ask for shorter answers;
• refusal (stop_reason: "refusal"): the model declined; show a polite message, don't loop;

• invalid structured output: validate and retry once, or fall back (Module 83).

• The official SDKs retry some errors automatically (by default twice, for connection errors, 408, 409, 429 and 5xx). You can set maxRetries and timeout on the client.

• Catch errors by type, most specific first:

try {
  const response = await client.messages.create({ /* ... */ });
  if (response.stop_reason === "refusal") return politeRefusal();
  if (response.stop_reason === "max_tokens") log.warn("answer truncated");
  // use the answer
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    return busyMessage();            // already retried by the SDK; tell the user to try shortly
  } else if (error instanceof Anthropic.AuthenticationError) {
    log.error("AI key invalid");      // configuration problem: alert yourself
    return unavailableMessage();
  } else if (error instanceof Anthropic.APIError) {
    log.error({ status: error.status }, "AI API error");
    return unavailableMessage();
  }
  throw error;
}

• Fail gracefully: the rest of your CRM must keep working if the AI provider is down. Show a clear message ("The assistant is unavailable right now; please search the documents directly"), and consider a fallback model or provider for important features.

• Monitor: error rates, retries and latency for AI calls, with alerts (Module 72).