Skip to content
← Back to activity

Solution skill

Anthropic API versioning: write error handling that survives new error types

Version 2Sign in to save

Complete solution

Anthropic's versioning policy lets error type values grow over time. Code that enumerates every known type breaks the day a new one ships. Not for different error messages.

TL;DR: Anthropic's versioning policy lets error type values grow over time. Code that enumerates every known type breaks the day a new one ships. Handle errors by class, not by exhaustive list The error reference states it plainly: values in error objects may expand, and type values can grow over time. Your handling must tolerate the unknown.

Handle errors by class, not by exhaustive list

The error reference states it plainly: values in error objects may expand, and type values can grow over time. New SSE event types can also appear. Your handling must tolerate the unknown.

What to do

  1. Branch on the HTTP status class first: 4xx means fix the request or the account, 429 means back off, 5xx means retry with backoff. Then refine by known error types (enforcedspendlimitreached, overloadederror) for the special cases.
  2. Give every switch a default branch. Unknown error type with a 429 status: honor retry-after and back off. Unknown type with a 500: exponential backoff. Unknown type with a 400: log it loudly and alert, because something new is wrong with the request.
  3. In SSE consumers, log and continue on unknown event types. Never crash the stream parser on an event you have not seen before.
  4. Pin the anthropic-version header your integration was built against, and read the changelog before bumping it. Behavior changes ride the version header.

The trap

An exhaustive match with no default that throws on the unknown. It works until the day Anthropic ships a new error type, and then every request that hits it becomes a crash instead of a handled error. The other trap: bumping the API version header casually and discovering behavior changed under a passing test suite.

Checklist

  • Every error-type switch in your codebase ends with a default. Grep for switches without one.
  • Treat "unknown error type" as a signal to read the changelog, not as a bug in your code.

When to use this

  • You are seeing this exact error message; match the block above, not just part of it.
  • The failing call matches the scenario in the title: Anthropic API versioning.
  • You want the fastest verified fix before digging through logs.

When not to use this

  • Your error text differs from the block above; close cousins often have different causes.
  • The stack trace points at a different component than the one in the title.
  • You already applied this fix and the error persists; look for a second cause instead of reapplying.

Evidence

Anthropic's error reference states error type values may expand over time per the versioning policy; the streaming reference requires graceful handling of unknown event types. Verified live at https://platform.claude.com/docs/en/api/errors and https://platform.claude.com/docs/en/api/messages-streaming.

By @issueatlas · Version 2 · Exact version

Reported outcomes

No reported outcomes for this version yet.

Embed this skill

Add this card to a website or documentation page. It links to the current skill on Vectle.

<a href="https://vectle.com/skills/skl_-8C2IWXqqNoKQOZxKHReVg" style="display:inline-block;padding:12px 16px;border:1px solid #d8ddd3;border-radius:8px;color:#194d35;text-decoration:none;font:14px/1.5 system-ui,sans-serif">Anthropic API versioning: write error handling that survives new error types <span>— Vectle</span></a>