services/api/ — Anthropic API Client Service

Contents

Architecture

flowchart TD
  U["User Query"] --> WR["withRetry Generator"]
  WR --> CL["getAnthropicClient()"]
  CL -->|First-party| AN["Anthropic SDK"]
  CL -->|Bedrock| BK["AnthropicBedrock SDK"]
  CL -->|Vertex| VX["AnthropicVertex SDK"]
  CL -->|Foundry| FD["AnthropicFoundry SDK"]
  AN --> API["Anthropic API"]
  BK --> API
  VX --> API
  FD --> API
  API -->|Stream| SR["Streaming Response"]
  SR --> LOG["logging.ts"]
  SR --> ERR["errors.ts / errorUtils.ts"]
  WR -->|429/529| RB["Retry with Backoff"]
  WR -->|Fallback| FM["FallbackTriggeredError"]
  RB --> CL
  FM --> CL
  LOG --> AN2["Analytics Events"]

Request Lifecycle

sequenceDiagram
  participant App as Claude Code
  participant WR as withRetry
  participant Client as AnthropicClient
  participant API as Anthropic API
  participant Err as Error Handler

  App->>WR: operation(client, retryContext)
  WR->>Client: getAnthropicClient(provider)
  Client->>API: POST /v1/messages (stream)
  alt Success
    API-->>WR: SSE token stream
    WR-->>App: yield tokens
  else 429 Rate Limited
    API-->>Err: APIError(429)
    Err->>WR: retryAfterMs
    WR->>WR: sleep(backoff)
    WR->>Client: retry request
  else 529 Overloaded
    API-->>Err: APIError(529)
    Err->>WR: consecutive529Errors++
    alt Under MAX_529_RETRIES
      WR->>Client: retry with backoff
    else Over threshold
      WR->>App: FallbackTriggeredError
    end
  end

Key Classes & Functions

Data Structures

Interactions

Configuration

Directory Map

api/
├── adminRequests.ts            ← Seat upgrade & limit increase requests
├── bootstrap.ts                ← Startup config fetch with disk caching
├── client.ts                   ← Multi-provider SDK client factory
├── claude.ts                   ← Core Claude model interaction
├── dumpPrompts.ts              ← Debug prompt/response capture to JSONL
├── emptyUsage.ts               ← Zero-initialized usage singleton
├── errorUtils.ts               ← SSL/TLS error detection & formatting
├── errors.ts                   ← Error classification & response parsing
├── filesApi.ts                 ← Files API upload/download with retry
├── firstTokenDate.ts           ← First usage date fetch & cache
├── grove.ts                    ← Terms/privacy notice management
├── logging.ts                  ← Analytics & gateway detection
├── metricsOptOut.ts            ← Org metrics opt-out (2-tier cache)
├── overageCreditGrant.ts       ← Overage credit eligibility cache
├── promptCacheBreakDetection.ts← Prompt cache fingerprint & break alerts
├── referral.ts                 ← Guest pass referral program
├── sessionIngress.ts           ← Session transcript persistence (409 recovery)
├── ultrareviewQuota.ts         ← Ultrareview quota peek
├── usage.ts                    ← Rate-limit utilization fetch
└── withRetry.ts                ← Resilient retry generator with fallback

Deep-Dive Highlights

Core mechanisms from this sub-module have been extracted into dedicated focus areas for in-depth exploration. Each topic covers one algorithm, protocol, or subsystem with diagrams and code walks.

Deep-Dive Pages

Gateway Detection

The logging module fingerprints AI gateway proxies from response headers to track infrastructure topology:

Code Examples

Example 1: Creating a Multi-Provider Client

import { getAnthropicClient } from './client';

// Factory detects provider from environment variables
const client = await getAnthropicClient({
  model: 'claude-sonnet-4-20250514',
  // Injects CLIENT_REQUEST_ID_HEADER for timeout tracing
  // Selects AnthropicBedrock if CLAUDE_CODE_USE_BEDROCK is set
  // Selects AnthropicVertex if CLAUDE_CODE_USE_VERTEX is set
  // Falls back to first-party Anthropic SDK with API key or OAuth
});

// Custom headers injected from ANTHROPIC_CUSTOM_HEADERS env var
// Container / remote session IDs added automatically
// Logger redirected to stderr with "[anthropic sdk]" prefix

Example 2: Resilient Retry with Model Fallback

import { withRetry, FallbackTriggeredError } from './withRetry';

const retryOptions: RetryOptions = {
  maxRetries: 10,
  model: 'claude-opus-4-20250514',
  fallbackModel: 'claude-sonnet-4-20250514',
  thinkingConfig: { enabled: true },
  signal: abortController.signal,
  querySource: 'repl_main_thread',
};

try {
  // withRetry is an async generator — yields error messages, returns final result
  const generator = withRetry(getAnthropicClient, sendRequest, retryOptions);
  for await (const errorMsg of generator) {
    // Display retry status to user (e.g., "Retrying in 2s...")
    displaySystemMessage(errorMsg);
  }
  const result = generator.return; // Final successful response
} catch (err) {
  if (err instanceof FallbackTriggeredError) {
    // Switch to fallback model and re-run
    retryOptions.model = err.fallbackModel;
  }
}

Example 3: File Upload with Retry

import { uploadSessionFiles, parseFileSpecs } from './filesApi';

const files = parseFileSpecs(['file_abc123:src/index.ts']);
const config: FilesApiConfig = {
  oauthToken: accessToken,
  sessionId: currentSessionId,
  baseUrl: 'https://api.anthropic.com',
};

// Uploads with exponential backoff (BASE_DELAY_MS=500, MAX_RETRIES=3)
// Path validation prevents directory traversal attacks
// MAX_FILE_SIZE_BYTES = 500MB per file
const results = await uploadSessionFiles(files, config);
for (const r of results) {
  if (r.success) console.log(`Uploaded ${r.path} → ${r.fileId}`);
  else console.error(`Failed ${r.path}: ${r.error}`);
}