Postconditions: what we check

• create · messages-create-no-try-catch

  error
  Whenmessages.create() called without try-catch or .catch() handler
  ThrowsAPIError with error.status and error.message
  Required handlingMUST wrap await client.messages.create() in try-catch block. Catch block should check error instanceof Anthropic.APIError and handle specific error types (RateLimitError, AuthenticationError, etc.) appropriately.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• create · messages-create-generic-catch

  warning
  Whenmessages.create() in try-catch but doesn't check error types
  Required handlingSHOULD check error type using instanceof or error.status code. Handle RateLimitError with retry logic (using retry-after header), AuthenticationError by validating API key, and server errors (500/529) with appropriate backoff.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• stream · messages-stream-no-try-catch

  error
  Whenmessages.stream() called without try-catch or .catch() handler
  ThrowsAPIError, can occur mid-stream after initial 200 response
  Required handlingMUST wrap await client.messages.stream() in try-catch block. Should also wrap stream iteration in try-catch to handle mid-stream errors. Check error types for proper recovery.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• stream · stream-abort-not-handled

  info
  WhenStream created but no abort/cleanup handling
  Required handlingSHOULD implement cancellation handling with stream.controller.abort() or break from stream iteration. Use finally blocks for cleanup.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2]
• Anthropic · api-key-not-validated

  warning
  WhenAnthropic client created without validating API key exists
  Required handlingSHOULD validate API key exists before client creation: if (!process.env.ANTHROPIC_API_KEY) throw new Error('Missing ANTHROPIC_API_KEY'). Consider using default apiKey validation from SDK.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• Anthropic · rate-limit-no-retry-logic

  info
  WhenAPI calls made without retry logic for 429 errors
  Required handlingSHOULD implement retry logic for 429 errors. Check retry-after header value and implement exponential backoff. Example: if (error instanceof RateLimitError) wait for error.headers['retry-after'] seconds before retry.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1]
• countTokens · count-tokens-no-try-catch

  error
  Whenmessages.countTokens() called without try-catch or .catch() handler
  ThrowsAPIError (BadRequestError 400, AuthenticationError 401, RateLimitError 429, InternalServerError 500)
  Required handlingMUST wrap await client.messages.countTokens() in try-catch. Despite being a read-only operation, it can fail with auth errors (bad API key) or rate limit errors when count token RPM quota is exceeded. Token counting has its own independent rate limit separate from message creation.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[3][1]
• countTokens · count-tokens-estimate-used-as-exact

  warning
  WhenToken count result used as exact limit without accounting for estimate variance
  Required handlingSHOULD add a safety margin (e.g., 5-10%) when using token counts as gates. Example: if (tokenCount.input_tokens * 1.05 > maxContextTokens) { ... } Do not use strict equality to gate on token counts.
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[3]
• batches.create · batches-create-no-try-catch

  error
  Whenmessages.batches.create() called without try-catch or .catch() handler
  ThrowsAPIError (BadRequestError 400, AuthenticationError 401, RateLimitError 429, InternalServerError 500)
  Required handlingMUST wrap await client.messages.batches.create() in try-catch. Batch creation can fail with BadRequestError (400) if any individual request params are invalid, AuthenticationError (401) if API key invalid, or RateLimitError (429) for quota exceeded. Check error.status and implement retry with exponential backoff for 429/500/529 errors.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[4][1]
• batches.create · batches-result-not-polled

  warning
  WhenBatch created but results never retrieved or polling logic absent
  Required handlingMUST implement result retrieval after batch creation. Either poll messages.batches.retrieve() until processing_status === 'ended', then stream results with messages.batches.results(); or use a background job (e.g. Inngest, BullMQ) triggered by webhook or periodic cron to poll and process results. Never create a batch without a retrieval plan.
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[4]
• batches.create · batches-individual-errors-not-handled

  warning
  WhenBatch results retrieved but individual request error statuses not checked
  Required handlingMUST check result.type before accessing result.message: if (result.type === 'succeeded') { process(result.message) } else if (result.type === 'errored') { handleError(result.error) } else if (result.type === 'expired') { requeue(result.custom_id) } Track errored count and alert when error rate exceeds threshold.
  costmediumin prodsilent failureusers seelost datavisibilitysilent
  Sources[4]
• beta.files.upload · files-upload-no-try-catch

  error
  Whenbeta.files.upload() called without try-catch or .catch() handler
  ThrowsAPIError (BadRequestError 400, AuthenticationError 401, RateLimitError 429, InternalServerError 500, 413 file too large, 403 storage limit exceeded)
  Required handlingMUST wrap await client.beta.files.upload() in try-catch. Check error.status: 413 = file too large (enforce 500 MB limit before upload); 403 = organization storage limit reached (implement storage quota checks); 400 = invalid filename or file type (validate before upload); 429 = rate limit (implement backoff, beta limit is ~100 req/min).
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5][1]
• beta.files.upload · files-upload-id-not-validated

  warning
  WhenFile ID from upload used in messages without checking upload succeeded
  Required handlingSHOULD verify upload result contains a valid id before using in messages: const file = await client.beta.files.upload({ file: ... }); if (!file.id) throw new Error('File upload returned no ID'); Then use file.id in the content block.
  costlowin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[5]
• messages.parse · messages-parse-no-try-catch

  error
  Whenmessages.parse() called without try-catch or .catch() handler
  ThrowsAPIError (identical error set to messages.create()), plus ZodError if schema parse fails
  Required handlingMUST wrap await client.messages.parse() in try-catch. Catch block should handle both APIError subclasses (instanceof Anthropic.APIError) and ZodError from schema validation failures. Note: a successful API call that produces output not matching the schema sets parsed_output to null rather than throwing — always check parsed_output !== null before using it.
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[1][2]
• messages.parse · messages-parse-null-output-unchecked

  warning
  Whenparsed_output used without null check after messages.parse()
  Required handlingMUST check parsed_output before using: const result = await client.messages.parse({ ... }); if (result.parsed_output === null) { // Handle refusal or incomplete output // Check result.stop_reason for diagnosis } else { use(result.parsed_output); }
  costlowin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[2]
• batches.cancel · batches-cancel-no-try-catch

  error
  Whenclient.messages.batches.cancel() called without try-catch or .catch() handler
  ThrowsAPIError hierarchy: NotFoundError (404) if message_batch_id does not exist or belongs to a different organization; AuthenticationError (401) on bad API key; RateLimitError (429) on quota; InternalServerError (500/529); APIConnectionError on network failure.
  Required handlingMUST wrap await client.messages.batches.cancel(id) in try-catch. Treat NotFoundError as non-fatal in bulk-cancel loops (the batch was already gone — that's the desired end state). Propagate other errors: try { await client.messages.batches.cancel(batchId); } catch (err) { if (err instanceof Anthropic.NotFoundError) { // Already gone — log and continue } else if (err instanceof Anthropic.APIError) { throw new Error(`Batch cancel failed: ${err.status} ${err.message}`); } else { throw err; } }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[6][1]
• batches.cancel · batches-cancel-state-not-rechecked

  warning
  Whenbatches.cancel() resolves successfully but caller does not poll the returned MessageBatch.processing_status to confirm the batch actually finished (vs sitting in "canceling" state with non-interruptible requests still completing).
  ThrowsNo exception. The returned MessageBatch.processing_status will be "canceling" (in transit) or "ended" (fully done). Caller that immediately calls batches.delete() will get a 4xx for "cannot delete in-progress batch" if processing_status is not "ended".
  Required handlingAfter cancel, poll batches.retrieve(id) until processing_status === 'ended' before deleting or treating the batch as terminal: await client.messages.batches.cancel(batchId); let batch; do { await new Promise(r => setTimeout(r, 2000)); batch = await client.messages.batches.retrieve(batchId); } while (batch.processing_status !== 'ended'); // Now safe to delete or treat as final
  costlowin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[6]
• batches.delete · batches-delete-no-try-catch

  error
  Whenclient.messages.batches.delete() called without try-catch or .catch() handler
  ThrowsAPIError hierarchy: BadRequestError (400 invalid_request_error) if the batch is still processing — Anthropic explicitly requires that the batch be in "ended" state before delete will succeed; NotFoundError (404) if the batch_id is invalid; AuthenticationError (401); RateLimitError (429); InternalServerError (500/529); APIConnectionError on network failure.
  Required handlingMUST wrap await client.messages.batches.delete(id) in try-catch. In batch deletion loops, log-and-continue on per-batch failure to ensure the worker completes: for (const id of batchIds) { try { await client.messages.batches.delete(id); } catch (err) { if (err instanceof Anthropic.BadRequestError) { // Likely still processing — cancel first, then retry later logger.warn('Skipping delete of in-progress batch', { id }); continue; } if (err instanceof Anthropic.NotFoundError) { continue; // already gone } logger.error('Batch delete failed', { id, err }); } }
  costmediumin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[7][1]
• batches.delete · batches-delete-without-prior-cancel

  warning
  Whenbatches.delete() is called on a batch whose processing_status has not been verified to be "ended". The caller assumed the batch was complete but it was actually still in_progress or canceling.
  ThrowsBadRequestError (400 invalid_request_error). The error message will indicate the batch is not in a deletable state.
  Required handlingMUST verify the batch is in "ended" state before deleting: const batch = await client.messages.batches.retrieve(id); if (batch.processing_status !== 'ended') { await client.messages.batches.cancel(id); // Poll until ended (see batches.cancel post-condition) } await client.messages.batches.delete(id);
  costlowin prodimmediate exceptionusers seedegraded performancevisibilityvisible
  Sources[7]
• batches.results · batches-results-no-try-catch

  error
  Whenclient.messages.batches.results() awaited without try-catch on the await OR on the for-await iteration
  ThrowsAPIError on the initial fetch (404 NotFoundError if batch_id invalid, 400 BadRequestError if processing_status !== 'ended', 401/429/500). APIConnectionError or generic Error during streaming iteration if the JSONL connection drops mid-stream.
  Required handlingMUST wrap BOTH the await and the iteration: try { const decoder = await client.messages.batches.results(batchId); try { for await (const item of decoder) { // Each item also needs per-result handling: if (item.result.type === 'errored') { handleErrored(item.custom_id, item.result.error); } else if (item.result.type === 'expired' || item.result.type === 'canceled') { handleNonSuccess(item.custom_id, item.result.type); } else { handleSucceeded(item.custom_id, item.result.message); } } } catch (streamErr) { // Connection drop mid-stream — note how many results were // processed and retry from that custom_id logger.error('Batch results stream interrupted', { streamErr }); } } catch (fetchErr) { if (fetchErr instanceof Anthropic.BadRequestError) { // Batch not in "ended" state yet } throw fetchErr; }
  costhighin prodimmediate exceptionusers seelost datavisibilityvisible
  Sources[6][2]
• batches.results · batches-results-individual-not-checked

  error
  Whenfor-await over batches.results() iterates items without checking item.result.type. Code treats every iterated item as a success and accesses item.result.message, which is undefined for type === 'errored' | 'canceled' | 'expired'.
  ThrowsTypeError at runtime: "Cannot read properties of undefined (reading 'content')" when accessing item.result.message.content on a non-succeeded result. The error type union for MessageBatchIndividualResponse is discriminated by result.type — accessing .message on the wrong branch is a TypeScript-level error that the runtime cannot distinguish without a narrowing check.
  Required handlingMUST narrow on item.result.type before accessing fields: for await (const item of decoder) { switch (item.result.type) { case 'succeeded': use(item.result.message); break; case 'errored': handleError(item.custom_id, item.result.error); break; case 'canceled': case 'expired': scheduleRetry(item.custom_id); break; } }
  costhighin prodsilent failureusers seelost datavisibilitysilent
  Sources[6]
• beta.webhooks.unwrap · webhooks-unwrap-no-try-catch

  error
  Whenclient.beta.webhooks.unwrap(body, { headers }) called without try-catch. unwrap is synchronous but can throw THREE distinct error types: plain Error (missing key), WebhookVerificationError (bad signature), or SyntaxError (JSON.parse failure on malformed body).
  Throws- Error('Webhook key must not be null in order to unwrap') if no webhookKey is configured on the client and no `key` option is passed. - WebhookVerificationError from standardwebhooks if the signature doesn't verify OR the webhook-timestamp header is outside the allowed clock-skew window. - SyntaxError from JSON.parse(body) if the body bytes aren't valid JSON.
  Required handlingMUST wrap in try-catch and distinguish the three failure modes: import { WebhookVerificationError } from 'standardwebhooks'; try { const event = client.beta.webhooks.unwrap(rawBody, { headers: req.headers, // key: process.env.ANTHROPIC_WEBHOOK_SIGNING_KEY }); await handleEvent(event); res.status(200).end(); } catch (err) { if (err instanceof WebhookVerificationError) { // Forged or expired — log + 401, do NOT 200 logger.warn('webhook verify failed', { err }); res.status(401).end(); return; } if (err instanceof SyntaxError) { // Malformed body — 400 res.status(400).end(); return; } // Missing key configuration — log loudly + 500 logger.error('webhook key not configured', { err }); res.status(500).end(); } NEVER return 200 from a verification-failed branch — Anthropic uses 200 as the "accepted" signal and stops retrying. A 4xx tells Anthropic the webhook was rejected and the next legitimate event is still delivered cleanly.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][8]
• beta.messages.toolRunner · tool-runner-no-try-catch

  error
  Whenclient.beta.messages.toolRunner() result is awaited or iterated without try-catch wrapping the await OR the for-await loop.
  ThrowsAPIError hierarchy on each underlying messages.create() call (BadRequestError, AuthenticationError, RateLimitError, InternalServerError, APIConnectionError); AnthropicError thrown by the runner itself ('ToolRunner concluded without a message from the server', 'Cannot iterate over a consumed stream'); whatever error the user's tool callback throws (re-thrown by the runner).
  Required handlingMUST wrap the await OR the for-await iteration in try-catch: try { const runner = client.beta.messages.toolRunner({ model: 'claude-opus-4-6', max_tokens: 1024, max_iterations: 10, tools: [...], messages: [...], }); for await (const msg of runner) { process(msg); } // OR: const final = await runner.runUntilDone(); } catch (err) { if (err instanceof Anthropic.APIError) { // Underlying messages.create() failed mid-loop } else if (err instanceof Anthropic.AnthropicError) { // Runner-level error (consumed stream, no message returned) } else { // User tool-callback threw — re-raised by runner } throw err; } Treat partial completion as lost work — the runner does not checkpoint, so a mid-loop failure requires the caller to re-seed the conversation history.
  costhighin prodimmediate exceptionusers seeservice unavailablevisibilityvisible
  Sources[2][1][9]
• beta.messages.toolRunner · tool-runner-max-iterations-not-set

  warning
  Whenbeta.messages.toolRunner() is called without max_iterations set, relying on the SDK default or no termination guard. The model can stay in tool_use → tool_result → tool_use loops indefinitely if tool callbacks always succeed and the model never returns a text-only final message.
  ThrowsNo exception directly. The runner consumes tokens (and dollars) until the API itself throws (RateLimitError 429, or context window InternalServerError) or the surrounding worker times out. Silent runaway cost is the dominant failure mode.
  Required handlingSHOULD set max_iterations explicitly: const runner = client.beta.messages.toolRunner({ model: 'claude-opus-4-6', max_tokens: 1024, max_iterations: 10, // hard cap tools: [...], messages: [...], }); OR provide an AbortSignal with a timeout: const controller = new AbortController(); setTimeout(() => controller.abort(), 60_000); const runner = client.beta.messages.toolRunner( { ... }, { signal: controller.signal }, ); For untrusted-input agentic loops, both should be set.
  costhighin prodsilent failureusers seedegraded performancevisibilitysilent
  Sources[2][9]

Sources

Every postcondition cites at least one of these. Grouped by source type; numbered to match the footnotes above.

Research notes

Curator notes from SOURCES.md captured when the profile was written so you can verify the reasoning, not just the rules.

if (error instanceof Anthropic.APIError) {
  console.error('API Error:', error.message);
  console.error('Status:', error.status);
  console.error('Request ID:', error.headers['request-id']);
}

if (error instanceof Anthropic.RateLimitError) {
  const retryAfter = error.headers['retry-after'];
  console.log(`Rate limited. Retry after ${retryAfter} seconds`);
  // Implement exponential backoff
}

if (error instanceof Anthropic.AuthenticationError) {
  throw new Error('Invalid ANTHROPIC_API_KEY. Check environment variable.');
}

import { ToolError } from '@anthropic-ai/sdk/lib/tools/BetaRunnableTool';

// Report tool execution errors to model
throw new ToolError('Invalid input: URL is malformed');

// Include images in error reports
throw new ToolError([
  { type: 'text', text: 'Failed to load page' },
  { type: 'image', source: { type: 'base64', data: screenshot, media_type: 'image/png' } }
]);

import { UnsupportedMCPValueError, mcpResourceToContent } from '@anthropic-ai/sdk/helpers/beta/mcp';

try {
  const content = mcpResourceToContent(resource);
} catch (error) {
  if (error instanceof UnsupportedMCPValueError) {
    console.error('Unsupported MCP value:', error.message);
  }
}

import Anthropic from '@anthropic-ai/sdk';

const anthropic = new Anthropic({
  apiKey: process.env.ANTHROPIC_API_KEY,
});

try {
  const message = await anthropic.messages.create({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello, Claude' }],
  });
  console.log(message.content);
} catch (error) {
  if (error instanceof Anthropic.APIError) {
    console.error('API Error:', error.status, error.message);
    console.error('Request ID:', error.headers['request-id']);
  } else {
    console.error('Unexpected error:', error);
  }
}

try {
  const message = await anthropic.messages.create({
    model: 'claude-opus-4-6',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Hello' }],
  });
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    // Rate limit - implement retry
    const retryAfter = parseInt(error.headers['retry-after'] || '60');
    console.log(`Rate limited. Retry in ${retryAfter}s`);
    await delay(retryAfter * 1000);
    // Retry request
  } else if (error instanceof Anthropic.AuthenticationError) {
    // Auth error - fix API key
    throw new Error('Invalid API key. Check ANTHROPIC_API_KEY environment variable.');
  } else if (error instanceof Anthropic.APIError) {
    // Server error or other API issue
    if (error.status === 500 || error.status === 529) {
      console.log('Server error. Implementing backoff...');
      // Exponential backoff
    } else {
      console.error('API Error:', error.status, error.message);
    }
  } else {
    throw error;
  }
}

try {
  const stream = await anthropic.messages.stream({
    model: 'claude-sonnet-4-5-20250929',
    max_tokens: 1024,
    messages: [{ role: 'user', content: 'Write a story' }],
  });

  try {
    for await (const chunk of stream) {
      if (chunk.type === 'content_block_delta') {
        process.stdout.write(chunk.delta.text);
      }
    }
  } catch (streamError) {
    console.error('Stream error:', streamError);
    stream.controller.abort();
  } finally {
    // Cleanup
  }
} catch (error) {
  if (error instanceof Anthropic.APIError) {
    console.error('Failed to start stream:', error.status, error.message);
  }
}

function createAnthropicClient() {
  const apiKey = process.env.ANTHROPIC_API_KEY;

  if (!apiKey || apiKey.trim() === '') {
    throw new Error('ANTHROPIC_API_KEY environment variable is required');
  }

  return new Anthropic({ apiKey });
}

async function createMessageWithRetry(
  anthropic: Anthropic,
  params: any,
  maxRetries = 3
) {
  let retries = 0;

  while (retries < maxRetries) {
    try {
      return await anthropic.messages.create(params);
    } catch (error) {
      if (error instanceof Anthropic.RateLimitError) {
        const retryAfter = parseInt(error.headers['retry-after'] || '1');
        const backoff = Math.min(retryAfter * 1000, Math.pow(2, retries) * 1000);

        console.log(`Rate limited. Waiting ${backoff}ms before retry ${retries + 1}/${maxRetries}`);
        await new Promise(resolve => setTimeout(resolve, backoff));
        retries++;
      } else if (error instanceof Anthropic.APIError && (error.status === 500 || error.status === 529)) {
        // Server error - exponential backoff
        const backoff = Math.pow(2, retries) * 1000;
        console.log(`Server error. Waiting ${backoff}ms before retry ${retries + 1}/${maxRetries}`);
        await new Promise(resolve => setTimeout(resolve, backoff));
        retries++;
      } else {
        // Non-retryable error
        throw error;
      }
    }
  }

  throw new Error(`Max retries (${maxRetries}) exceeded`);
}

// Current (bad) pattern
try {
  const response = await anthropic.messages.create({...});
} catch (error: any) {
  console.error("Error calling Anthropic API:", error);
  return new NextResponse(
    JSON.stringify({ message: "An error occurred" }),
    { status: 500 }
  );
}

try {
  const response = await anthropic.messages.create({...});
} catch (error) {
  if (error instanceof Anthropic.RateLimitError) {
    return new NextResponse(
      JSON.stringify({ message: "Rate limit exceeded", retryAfter: error.headers['retry-after'] }),
      { status: 429 }
    );
  } else if (error instanceof Anthropic.AuthenticationError) {
    return new NextResponse(
      JSON.stringify({ message: "Invalid API key" }),
      { status: 401 }
    );
  } else if (error instanceof Anthropic.APIError) {
    return new NextResponse(
      JSON.stringify({ message: error.message, requestId: error.headers['request-id'] }),
      { status: error.status || 500 }
    );
  }
  throw error;
}