anymous 1.3.0 → 1.3.2

package/skills/claude-api/shared/anthropic-cli.md

@@ -1,246 +0,0 @@
-# Anthropic CLI (`ant`)
-
-The `ant` CLI exposes every Claude API resource as a shell subcommand. Compared to `curl`: request bodies are built from typed flags or piped YAML instead of hand-written JSON, `@path` inlines file contents into any string field, `--transform` extracts fields with a GJSON path (no `jq`), list endpoints auto-paginate (cap total results with `--max-items N`; `--limit` only sets the server page size), and the `beta:` prefix auto-sets the right `anthropic-beta` header.
-
-## When to use the CLI vs the SDK
-
-**CLI for the control plane, SDK for the data plane.** Agents and environments are relatively static resources you define, configure, and debug with `ant` — check the YAML into your repo, apply from CI, inspect from a terminal. Sessions are dynamic and driven by your application through the SDK — create per task, stream events, react to tool calls, integrate into your product. Both hit the same API; the split is about where the call lives, not what's possible.
-
-| | Control plane → `ant` | Data plane → SDK |
-|---|---|---|
-| Resources | agents, environments, skills, vaults, files | sessions, events |
-| Cadence | Once per deploy / ad-hoc | Every task / every turn |
-| Lives in | `*.yaml` in your repo + CI + terminal | Application code |
-| Typical calls | `create < agent.yaml`, `update --version N`, `list`, `retrieve`, `archive`, `--debug` | `sessions.create()`, `events.stream()`, `events.send()` |
-
-## Install and auth
-
-```sh
-# macOS
-brew install anthropics/tap/ant
-xattr -d com.apple.quarantine "$(brew --prefix)/bin/ant"
-
-# Linux / WSL — pick the release from github.com/anthropics/anthropic-cli/releases
-curl -fsSL "https://github.com/anthropics/anthropic-cli/releases/download/v${VERSION}/ant_${VERSION}_$(uname -s | tr A-Z a-z)_$(uname -m | sed -e s/x86_64/amd64/ -e s/aarch64/arm64/).tar.gz" \
-  | sudo tar -xz -C /usr/local/bin ant
-
-# Or from source (Go 1.22+)
-go install github.com/anthropics/anthropic-cli/cmd/ant@latest
-```
-
-**Auth** — the CLI resolves credentials the same way the SDKs do (first match wins): explicit flags, then `ANTHROPIC_API_KEY`, then `ANTHROPIC_AUTH_TOKEN`, then the `ANTHROPIC_PROFILE`-selected or active profile, then Workload Identity Federation env vars, then the default profile on disk. Override the host with `ANTHROPIC_BASE_URL` or `--base-url`.
-
-- **API key**: set `ANTHROPIC_API_KEY` in the environment.
-- **OAuth profile** (no static key to manage): `ant auth login` opens a browser, exchanges for a short-lived token, and stores a profile under `$ANTHROPIC_CONFIG_DIR` (default `~/.config/anthropic/` on Linux/macOS, `%APPDATA%\Anthropic` on Windows — `configs/<profile>.json` for settings, `credentials/<profile>.json` for tokens). Subsequent `ant` (and SDK) calls pick it up automatically — a bare `Anthropic()` client works after login, but scripts that read `ANTHROPIC_API_KEY` directly do not. Claude Code and the Claude Agent SDK honor the same profile resolution. `ant auth status` shows which credential source and profile won (it reports status only — don't script against its exit code as a health check); `ant auth logout` clears the active profile (`--all` for every profile). On a remote host without a browser, `ant auth login --no-browser` prints the authorize URL and accepts the code back in the terminal.
-- **Non-interactive workloads** (CI, servers, containers): interactive login is for development on your own machine — use Workload Identity Federation instead (see the authentication docs via `shared/live-sources.md`).
-
-> **The #1 auth trap:** profiles are only consulted when no API key is set. A stale exported `ANTHROPIC_API_KEY` silently overrides every profile — requests hit whatever org/workspace that key is scoped to. `ant auth status` shows which source won; unset the key (or per-command: `env -u ANTHROPIC_API_KEY ant …`) before relying on a profile. Truly **unset** it — an empty `ANTHROPIC_API_KEY=""` still wins its precedence slot and authenticates with an empty key. The same shadowing applies in reverse to Claude Code: after `ant auth login`, Claude Code may warn about an auth conflict between the profile and its own `/login` credential — keep one (use the profile and `/logout` in Claude Code, or `ant auth logout` to keep Claude Code's own login).
-
-**Named profiles** — an interactive-login token is bound to a single org+workspace, and the API only shows resources belonging to that workspace. If an agent, session, or file you created "disappears", the usual cause is a token scoped to a different workspace than the one that created it (`ant auth status` shows the active workspace). Multi-workspace work means one profile per workspace:
-
-```sh
-ant auth login --profile <name>                  # creates the profile if it doesn't exist; org/workspace picker in browser
-ant auth login --profile <name> --workspace-id wrkspc_01...   # bind directly, skip the picker
-ant profile activate <name>                      # switch the default profile
-ant --profile <name> models list                 # one-off; equivalent: ANTHROPIC_PROFILE=<name> ant models list
-ant profile list                                 # inspect
-ant profile set workspace_id wrkspc_01... --profile <name>    # edit config keys (workspace_id, base_url, organization_id, …)
-```
-
-`ant profile set` edits an existing profile's config — it never creates one, and it does **not** rebind already-issued credentials; run `ant auth login` again under that profile to mint a token for the new target. Pointing `ANTHROPIC_PROFILE` at a profile that doesn't exist is an error, not a fall-through. Refresh tokens eventually hard-expire (they don't slide with use) — when a previously working profile starts failing auth, re-run `ant auth login` before debugging anything else.
-
-**Scopes** — a profile's OAuth scope set is requested at login (`--scope`) and persists on the profile (`scope` is also a `profile set` config key; like other config edits, changing it requires a fresh `ant auth login` to take effect). Privileged scopes — e.g. `org:admin` for organization-administration endpoints — are **not** in the default scope set: pass the full set you want explicitly (`ant auth login --profile admin --scope "... org:admin"`), and the server grants a privileged scope only if your role actually has it. Because the scope set rides on every token the profile mints, keep privileged work on a dedicated profile (`admin` vs `default`) and do day-to-day inference on the unprivileged one, switching with `--profile`/`ANTHROPIC_PROFILE`. Check `ant auth login --help` for the current scope list, and `ant auth status` to see what the active token carries.
-
-To hand the active credential to a subprocess or raw-HTTP script:
-
-```sh
-# Bare access token — for curl's Authorization header
-curl https://api.anthropic.com/v1/messages \
-  -H "Authorization: Bearer $(ant auth print-credentials --access-token)" \
-  -H "anthropic-version: 2023-06-01" \
-  -H "anthropic-beta: oauth-2025-04-20" \
-  -H "content-type: application/json" \
-  -d '{"model": "claude-opus-5", "max_tokens": 1024, "messages": [{"role": "user", "content": "Hello"}]}'
-
-# .env format — sets ANTHROPIC_AUTH_TOKEN (and ANTHROPIC_BASE_URL if the profile has one).
-# Output is bare KEY=value (no `export`), so use `set -a` to auto-export for child processes:
-set -a; eval "$(ant auth print-credentials --env)"; set +a
-python my_script.py   # SDK picks up ANTHROPIC_AUTH_TOKEN
-```
-
-OAuth tokens go on `Authorization: Bearer` (not `x-api-key:`) **plus the `anthropic-beta: oauth-2025-04-20` header** — converting a raw curl/httpx script from an API key is a header change, not a key swap. The beta header requirement is endpoint-dependent (some endpoints happen to work without it; `/v1/messages` does not) — always send it so requests don't break when you switch endpoints. The token is short-lived and not auto-refreshed when passed via env var, so re-run `print-credentials` before it expires for long-running scripts (`print-credentials` itself refreshes the token if needed). If both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` are set, the SDKs send both and the API rejects the request — unset `ANTHROPIC_API_KEY` before `eval`ing the `--env` output.
-
-**Foot-gun:** `ant auth print-credentials` with **no flags** prints the entire credentials JSON, not the bare token — putting that in an `Authorization` header yields an empty response or HTTP/2 protocol error. Always use `--access-token` for headers (it always reads the named/active profile; a set `ANTHROPIC_API_KEY` doesn't override credential printing).
-
-## Command structure
-
-```
-ant <resource>[:<subresource>] <action> [flags]
-```
-
-Beta resources (agents, sessions, environments, deployments, skills, vaults, memory stores) live under `beta:` — the CLI auto-sends the right `anthropic-beta` header, so don't pass it yourself unless overriding with `--beta <header>`. For self-hosted environments, `ant beta:worker poll/run` and `ant beta:environments:work stats/stop` drive and monitor the work queue — see `shared/managed-agents-self-hosted-sandboxes.md`.
-
-```sh
-ant models list
-ant messages create --model claude-opus-5 --max-tokens 1024 --message '{role: user, content: "Hello"}'
-ant beta:agents retrieve --agent-id agent_01...
-ant beta:sessions:events list --session-id session_01...
-```
-
-`ant --help` lists resources; append `--help` to any subcommand for its flags.
-
-## Global flags
-
-| Flag | Purpose |
-| --- | --- |
-| `--format` | `auto` (default: pretty if TTY, compact if piped), `json`, `jsonl`, `yaml`, `pretty`, `raw`, `explore` (interactive TUI) |
-| `--transform` | GJSON path applied to the response (per-item on list endpoints). Not applied when `--format raw`. |
-| `-r`, `--raw-output` | If the transformed result is a string, print it without quotes (jq semantics). Pair with `--transform` for scalar capture. |
-| `--max-items` | Cap total results returned from auto-paginating list endpoints (distinct from `--limit`, which is the server page size). |
-| `--format-error` / `--transform-error` | Same as `--format`/`--transform`, applied to error responses. `-r` does not apply to the error path — use `--format-error yaml` for unquoted error scalars. |
-| `--base-url` | Override API host |
-| `--debug` | Print full HTTP request + response to stderr (API key redacted) |
-
-## Output — `--transform` + `--format`
-
-`--transform` takes a [GJSON path](https://github.com/tidwall/gjson/blob/master/SYNTAX.md). On list endpoints it runs **per item**, not on the envelope.
-
-```sh
-ant beta:agents list --transform '{id,name,model}' --format jsonl
-```
-
-**Extract a scalar for shell use:** pair `--transform` with `-r` (`--raw-output` — prints strings unquoted, jq-style):
-
-```sh
-AGENT_ID=$(ant beta:agents create --name "My Agent" --model '{id: claude-sonnet-5}' \
-  --transform id -r)
-```
-
-## Input — flags, stdin, `@file`
-
-**Flags** — scalar fields map directly. Structured fields accept relaxed-YAML syntax (unquoted keys) or strict JSON. Repeatable flags build arrays (each `--tool`, `--event`, `--message` appends one element):
-
-```sh
-ant beta:agents create \
-  --name "Research Agent" \
-  --model '{id: claude-opus-5}' \
-  --tool '{type: agent_toolset_20260401}' \
-  --tool '{type: custom, name: search_docs, input_schema: {type: object, properties: {query: {type: string}}}}'
-```
-
-**Stdin** — pipe a full JSON or YAML body. Merged with flags; flags win on conflict (for array fields, any flag **replaces** the stdin array entirely — it does not append). Quote the heredoc delimiter (`<<'YAML'`) to disable shell expansion inside the body:
-
-```sh
-ant beta:agents create <<'YAML'
-name: Research Agent
-model: claude-opus-5
-system: |
-  You are a research assistant. Cite sources for every claim.
-tools:
-  - type: agent_toolset_20260401
-YAML
-```
-
-**`@file` references** — inline a file's contents into any string-valued field. Inside structured flag values, quote the path. Binary files are auto-base64'd; force with `@file://` (text) or `@data://` (base64). Escape a literal leading `@` as `\@`.
-
-```sh
-ant beta:agents create --name "Researcher" --model '{id: claude-sonnet-5}' --system @./prompts/researcher.txt
-
-ant messages create --model claude-opus-5 --max-tokens 1024 \
-  --message '{role: user, content: [
-    {type: document, source: {type: base64, media_type: application/pdf, data: "@./scan.pdf"}},
-    {type: text, text: "Extract the text from this scanned document."}
-  ]}' \
-  --transform 'content.0.text' -r
-```
-
-Flags that natively take a file path (e.g. `--file` on `beta:files upload`) accept a bare path without `@`.
-
-## Version-controlled Managed Agents resources
-
-This is the recommended flow for defining agents and environments — check the YAML into your repo and sync via `create` (first time) / `update` (thereafter). See `shared/managed-agents-core.md` for the field reference.
-
-```yaml
-# summarizer.agent.yaml
-name: Summarizer
-model: claude-sonnet-5
-system: |
-  You are a helpful assistant that writes concise summaries.
-tools:
-  - type: agent_toolset_20260401
-```
-
-```sh
-# Create (once) — capture the ID
-AGENT_ID=$(ant beta:agents create < summarizer.agent.yaml --transform id -r)
-
-# Update (CI) — needs ID + current version (optimistic lock)
-ant beta:agents update --agent-id "$AGENT_ID" --version 1 < summarizer.agent.yaml
-```
-
-Same pattern for environments (`ant beta:environments create|update < env.yaml`), then start a session with both IDs:
-
-```sh
-ant beta:sessions create --agent "$AGENT_ID" --environment-id "$ENV_ID" --title "Task"
-ant beta:sessions:events send --session-id "$SID" \
-  --event '{type: user.message, content: [{type: text, text: "Summarize X"}]}'
-ant beta:sessions:events list --session-id "$SID" --transform 'content.0.text' -r
-ant beta:sessions:events stream --session-id "$SID"   # live event stream
-```
-
-### Interactive session loop (stream-before-send)
-
-`ant beta:sessions:events stream` only delivers events emitted *after* the stream opens — so open it **before** sending the kickoff to avoid missing early events. Use process substitution to hold the stream on a file descriptor, send, then read:
-
-```sh
-exec {stream}< <(ant beta:sessions:events stream --session-id "$SID" \
-  --transform '{type,text:content.#(type=="text").text,err:error.message}' --format yaml)
-
-ant beta:sessions:events send --session-id "$SID" > /dev/null <<'YAML'
-events:
-  - type: user.message
-    content:
-      - type: text
-        text: Summarize the repo README
-YAML
-
-type=
-while IFS= read -r -u "$stream" line; do
-  case "$line" in
-    type:\ session.status_idle) break ;;
-    type:\ session.error)
-      IFS= read -r -u "$stream" next || next=
-      case "$next" in err:\ *) msg=${next#err: } ;; *) msg=unknown ;; esac
-      printf '\n[Error: %s]\n' "$msg"; break ;;
-    type:\ *) type=${line#type: } ;;
-    text:*)
-      [[ $type == agent.message ]] || continue
-      val=${line#text: }
-      case "$val" in '|-'|'|') ;; *) printf '%s' "$val" ;; esac ;;
-    \ \ *)
-      if [[ $type == agent.message ]]; then printf '%s\n' "${line#  }"; fi ;;
-  esac
-done
-exec {stream}<&-
-```
-
-This works for interactive exploration and demos. For application code that needs to react to `agent.tool_use` / `agent.custom_tool_use` events, reconnect after drops, or dedup against `events.list`, use the SDK — see `shared/managed-agents-client-patterns.md`.
-
-## Scripting patterns
-
-`--transform id -r` on a list endpoint emits one bare ID per line — compose with `xargs`, or use `--max-items N` to bound the result set without piping through `head`:
-
-```sh
-FIRST=$(ant beta:agents list --transform id -r --max-items 1)
-ant beta:agents:versions list --agent-id "$FIRST" --transform '{version,created_at}' --format jsonl
-```
-
-Error shaping mirrors the success path (note: `-r` does not apply to error output — use `--format-error yaml` for an unquoted scalar here):
-
-```sh
-ant beta:agents retrieve --agent-id bogus --transform-error error.message --format-error yaml 2>&1
-```
-
-Shell completion: `ant @completion {zsh|bash|fish|powershell}`.
-
-For the full, always-current reference (including per-endpoint flags), WebFetch the **Anthropic CLI** URL in `shared/live-sources.md`.

package/skills/claude-api/shared/claude-platform-on-aws.md

@@ -1,59 +0,0 @@
-# Claude Platform on AWS
-
-**Anthropic-operated** access to the Claude Developer Platform through AWS infrastructure — SigV4 authentication, AWS IAM access control, and AWS Marketplace billing. Because Anthropic operates it, **the API surface matches first-party with same-day parity** — for per-feature exceptions, see `shared/platform-availability.md` (the single source of truth; do not rely on an inline exception list here). Model IDs are the bare first-party strings (`claude-opus-5`, `claude-sonnet-5`) — **no provider prefix**.
-
-> **Not the same as Amazon Bedrock.** Bedrock is partner-operated (AWS runs the service; release schedules vary, feature subset, `anthropic.`-prefixed model IDs). Claude Platform on AWS and Bedrock coexist; pick by whether you need AWS-native IAM/billing with full Anthropic API parity (this page) vs. Bedrock's own ecosystem.
-
----
-
-## Client & install
-
-| Language | Install | Client |
-|---|---|---|
-| Python | `pip install -U "anthropic[aws]"` | `from anthropic import AnthropicAWS` → `AnthropicAWS()` |
-| TypeScript | `npm install @anthropic-ai/aws-sdk` | `import AnthropicAws from "@anthropic-ai/aws-sdk"` → `new AnthropicAws()` |
-| Go | `go get github.com/anthropics/anthropic-sdk-go` | `import anthropicaws "github.com/anthropics/anthropic-sdk-go/aws"` → `anthropicaws.NewClient(ctx, anthropicaws.ClientConfig{})` |
-| C# | `dotnet add package Anthropic.Aws` | `new AnthropicAwsClient()` |
-| Java | See SDK repo in `shared/live-sources.md` | See SDK repo in `shared/live-sources.md` |
-| Ruby | `gem install anthropic aws-sdk-core` | See SDK repo in `shared/live-sources.md` |
-| PHP | `composer require anthropic-ai/sdk aws/aws-sdk-php` | See SDK repo in `shared/live-sources.md` |
-
-After construction, **use the client exactly as you would `Anthropic()`** — `client.messages.create(...)`, `client.beta.sessions.*`, etc., with bare model IDs.
-
-```python
-from anthropic import AnthropicAWS
-
-client = AnthropicAWS()  # region + workspace_id from env; see below
-client.messages.create(
-    model="claude-opus-5",
-    max_tokens=1024,
-    messages=[{"role": "user", "content": "Hello"}],
-)
-```
-
----
-
-## Required configuration
-
-Two values must be available (constructor args or environment) — **there is no default fallback** for either:
-
-| Value | Env var | Notes |
-|---|---|---|
-| AWS region | `AWS_REGION` | Required. Unlike `AnthropicBedrock`, there is no `us-east-1` fallback. |
-| Workspace ID | `ANTHROPIC_AWS_WORKSPACE_ID` | Required. Routes requests to your Claude workspace. |
-
-Endpoint pattern: `https://aws-external-anthropic.{region}.api.aws/v1/...`. Requests are SigV4-signed with service name `aws-external-anthropic`.
-
-## Authentication
-
-The client resolves AWS credentials via the standard precedence chain: explicit constructor args → environment (`AWS_ACCESS_KEY_ID`/`AWS_SECRET_ACCESS_KEY`/`AWS_SESSION_TOKEN`) → shared profile → assumed role / instance metadata.
-
-**Short-term API keys** are also supported for cases where SigV4 isn't practical (e.g., browser, simple scripts). Mint one with the per-language token-generator package; pass it as `api_key` on the client. Lifetime is the **lesser of** the requested duration, the underlying credential's expiry, and **12 hours**. For package names and IAM details, WebFetch the Claude Platform on AWS page in `shared/live-sources.md`.
-
----
-
-## What to tell users
-
-- Treat it as first-party: every section of this skill applies unchanged. Do **not** apply Bedrock's feature-availability mask.
-- Model IDs are bare (`claude-opus-5`). Do **not** add an `anthropic.` prefix.
-- A missing region or `workspace_id` throws at client-construction time (no request is sent). A **403** means the request reached the server — check for a **wrong** `workspace_id` or a missing IAM action on the principal. See the IAM actions reference in `shared/live-sources.md`.

package/skills/claude-api/shared/error-codes.md

@@ -1,257 +0,0 @@
-# HTTP Error Codes Reference
-
-This file documents HTTP error codes returned by the Claude API, their common causes, and how to handle them. For language-specific error handling examples, see the `python/` or `typescript/` folders.
-
-## Error Code Summary
-
-| Code | Error Type              | Retryable | Common Cause                         |
-| ---- | ----------------------- | --------- | ------------------------------------ |
-| 400  | `invalid_request_error` | No        | Invalid request format or parameters |
-| 401  | `authentication_error`  | No        | Invalid or missing API key           |
-| 403  | `permission_error`      | No        | API key lacks permission             |
-| 404  | `not_found_error`       | No        | Invalid endpoint or model ID         |
-| 413  | `request_too_large`     | No        | Request exceeds size limits          |
-| 429  | `rate_limit_error`      | Yes       | Too many requests                    |
-| 500  | `api_error`             | Yes       | Anthropic service issue              |
-| 529  | `overloaded_error`      | Yes       | API is temporarily overloaded        |
-
-## Detailed Error Information
-
-### 400 Bad Request
-
-**Causes:**
-
-- Malformed JSON in request body
-- Missing required parameters (`model`, `max_tokens`, `messages`)
-- Invalid parameter types (e.g., string where integer expected)
-- Empty messages array
-- Messages not alternating user/assistant
-
-**Example error:**
-
-```json
-{
-  "type": "error",
-  "error": {
-    "type": "invalid_request_error",
-    "message": "messages: roles must alternate between \"user\" and \"assistant\""
-  },
-  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
-}
-```
-
-**Fix:** Validate request structure before sending. Check that:
-
-- `model` is a valid model ID
-- `max_tokens` is a positive integer
-- `messages` array is non-empty and alternates correctly
-
----
-
-### 401 Unauthorized
-
-**Causes:**
-
-- Missing `x-api-key` header or `Authorization` header
-- Invalid API key format
-- Revoked or deleted API key
-- OAuth bearer token sent via `x-api-key` instead of `Authorization: Bearer`
-- Both `ANTHROPIC_API_KEY` and `ANTHROPIC_AUTH_TOKEN` set — the SDK sends both headers and the API rejects the request
-
-**Fix:** Set `ANTHROPIC_API_KEY`, or run `ant auth login` and leave the client constructor empty. For raw HTTP with an OAuth token, use `Authorization: Bearer <token>` (not `x-api-key:`).
-
----
-
-### 403 Forbidden
-
-**Causes:**
-
-- API key doesn't have access to the requested model
-- Organization-level restrictions
-- Attempting to access beta features without beta access
-
-**Fix:** Check your API key permissions in the Console. You may need a different API key or to request access to specific features.
-
----
-
-### 404 Not Found
-
-**Causes:**
-
-- Typo in model ID (e.g., `claude-sonnet-4.6` instead of `claude-sonnet-4-6`)
-- Using deprecated model ID
-- Invalid API endpoint
-
-**Fix:** Use exact model IDs from the models documentation. You can use aliases (e.g., `claude-opus-5`).
-
----
-
-### 413 Request Too Large
-
-**Causes:**
-
-- Request body exceeds maximum size
-- Too many tokens in input
-- Image data too large
-
-**Fix:** Reduce input size — truncate conversation history, compress/resize images, or split large documents into chunks.
-
----
-
-### 400 Validation Errors
-
-Some 400 errors are specifically related to parameter validation:
-
-- `max_tokens` exceeds model's limit
-- Invalid `temperature` value (must be 0.0-1.0)
-- `budget_tokens` >= `max_tokens` in extended thinking
-- Invalid tool definition schema
-
-**Model-specific 400s on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7:**
-
-- `temperature`, `top_p`, `top_k` are removed — sending any of them returns 400. Delete the parameter; see `shared/model-migration.md` → Per-SDK Syntax Reference.
-- `thinking: {type: "enabled", budget_tokens: N}` is removed — sending it returns 400. Use `thinking: {type: "adaptive"}` instead.
-- **Claude Opus 5:** `thinking: {type: "disabled"}` returns 400 when `effort` is `xhigh` or `max` — it is accepted at `high` or below. Thinking is on by default, so omitting the param runs adaptive rather than disabling it.
-- **Fable 5 only:** an explicit `thinking: {type: "disabled"}` returns 400 at any effort (it is accepted on Opus 4.8/4.7). Omit the `thinking` param entirely instead.
-- **Fable 5 only:** if the organization is set to zero data retention (ZDR) — or any retention below the required 30 days — then **all** Fable 5 requests return `400 invalid_request_error`, even with a perfectly valid payload. Check the org's retention configuration before debugging the request body.
-
-**Common mistake with extended thinking on older models (Opus 4.6 and earlier):**
-
-```
-# Wrong: budget_tokens must be < max_tokens
-thinking: budget_tokens=10000, max_tokens=1000  → Error!
-
-# Correct
-thinking: budget_tokens=10000, max_tokens=16000
-```
-
----
-
-### 429 Rate Limited
-
-**Causes:**
-
-- Exceeded requests per minute (RPM)
-- Exceeded tokens per minute (TPM)
-- Exceeded tokens per day (TPD)
-
-**Headers to check:**
-
-- `retry-after`: Seconds to wait before retrying
-- `x-ratelimit-limit-*`: Your limits
-- `x-ratelimit-remaining-*`: Remaining quota
-
-**Fix:** The Anthropic SDKs automatically retry 429 and 5xx errors with exponential backoff (default: `max_retries=2`). For custom retry behavior, see the language-specific error handling examples.
-
----
-
-### 500 Internal Server Error
-
-**Causes:**
-
-- Temporary Anthropic service issue
-- Bug in API processing
-
-**Fix:** Retry with exponential backoff. If persistent, check [status.anthropic.com](https://status.anthropic.com).
-
----
-
-### 529 Overloaded
-
-**Causes:**
-
-- High API demand
-- Service capacity reached
-
-**Fix:** Retry with exponential backoff. Consider using a different model (Haiku is often less loaded), spreading requests over time, or implementing request queuing.
-
----
-
-## Common Mistakes and Fixes
-
-| Mistake                         | Error            | Fix                                                     |
-| ------------------------------- | ---------------- | ------------------------------------------------------- |
-| `temperature`/`top_p`/`top_k` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400 | Remove the parameter (see `shared/model-migration.md`)  |
-| `budget_tokens` on Claude Opus 5 / Fable 5 / Opus 4.8 / 4.7 | 400  | Use `thinking: {type: "adaptive"}`                      |
-| `thinking: {type: "disabled"}` on Fable 5 | 400    | Omit the `thinking` param entirely (accepted on Opus 4.8/4.7) |
-| Org set to ZDR / retention below 30 days (Fable 5) | 400 on every request | Fix the org's data-retention configuration — the payload isn't the problem |
-| `budget_tokens` >= `max_tokens` (older models) | 400 | Ensure `budget_tokens` < `max_tokens`                  |
-| Typo in model ID                | 404              | Use valid model ID like `claude-opus-5`               |
-| First message is `assistant`    | 400              | First message must be `user`                            |
-| Consecutive same-role messages  | 400              | Alternate `user` and `assistant`                        |
-| API key in code                 | 401 (leaked key) | Use environment variable                                |
-| Custom retry needs              | 429/5xx          | SDK retries automatically; customize with `max_retries` |
-
-## Typed Exceptions in SDKs
-
-**Always use the SDK's typed exception classes** instead of checking error messages with string matching. Each HTTP status code maps to a specific exception class per SDK.
-
-### Exception class names by language
-
-| HTTP | Python (`anthropic.*`) / TypeScript (`Anthropic.*`) | Ruby (`Anthropic::Errors::*`) | Java (`com.anthropic.errors.*`) | C# | PHP (`Anthropic\Core\Exceptions\*`) |
-|---|---|---|---|---|---|
-| 400 | `BadRequestError` | `BadRequestError` | `BadRequestException` | `AnthropicBadRequestException` | `BadRequestException` |
-| 401 | `AuthenticationError` | `AuthenticationError` | `UnauthorizedException` | `AnthropicUnauthorizedException` | `AuthenticationException` |
-| 403 | `PermissionDeniedError` | `PermissionDeniedError` | `PermissionDeniedException` | `AnthropicForbiddenException` | `PermissionDeniedException` |
-| 404 | `NotFoundError` | `NotFoundError` | `NotFoundException` | `AnthropicNotFoundException` | `NotFoundException` |
-| 422 | `UnprocessableEntityError` | `UnprocessableEntityError` | `UnprocessableEntityException` | `AnthropicUnprocessableEntityException` | `UnprocessableEntityException` |
-| 429 | `RateLimitError` | `RateLimitError` | `RateLimitException` | `AnthropicRateLimitException` | `RateLimitException` |
-| ≥500 | `InternalServerError` | `InternalServerError` | `InternalServerException` | `Anthropic5xxException` | `InternalServerException` |
-| net | `APIConnectionError` | `APIConnectionError` | `AnthropicIoException` | `AnthropicIOException` | `APIConnectionException` |
-| base | `APIError` (both); `APIStatusError` (Python only) | `APIStatusError` / `APIError` | `AnthropicServiceException` | `AnthropicApiException` | `APIStatusException` / `APIException` |
-
-The Ruby and PHP classes live in a dedicated errors namespace — write `Anthropic::Errors::RateLimitError` and `Anthropic\Core\Exceptions\RateLimitException` (not bare `Anthropic::RateLimitError`). All 4xx C# exceptions also inherit from `Anthropic4xxException`.
-
-### Catch most-specific first, in a chain
-
-Order `catch`/`except`/`rescue` clauses from the most specific subclass to the base class, with a separate clause for each category you handle differently — retryable (429, ≥500, network) vs. non-retryable (4xx). The SDK defines a distinct class per status for exactly this reason; a single broad catch-all discards that information.
-
-```python
-try:
-    msg = client.messages.create(...)
-except anthropic.NotFoundError as e:          # 404 — e.g. bad model ID
-    ...
-except anthropic.RateLimitError as e:         # 429 — back off and retry
-    ...
-except anthropic.APIStatusError as e:         # any other non-2xx HTTP response
-    print(e.status_code, e.message)
-except anthropic.APIConnectionError as e:     # network failure before a response
-    ...
-```
-
-The same chain shape applies in every SDK: TypeScript `instanceof Anthropic.NotFoundError` → `RateLimitError` → `APIConnectionError` → `APIError` (check `APIConnectionError` before `APIError` — in the TypeScript SDK it's a subclass of `APIError`, unlike Python where it's a sibling); Ruby `rescue Anthropic::Errors::NotFoundError` → `…::RateLimitError` → `…::APIStatusError`; Java `catch (NotFoundException) … catch (RateLimitException) … catch (AnthropicServiceException)`; C# `catch (AnthropicNotFoundException) … catch (AnthropicRateLimitException) … catch (AnthropicApiException)`; PHP `catch (NotFoundException) … catch (RateLimitException) … catch (APIStatusException)`.
-
-### Go — `errors.As` then branch on status
-
-The Go SDK returns a single `*anthropic.Error` for all non-2xx responses. Unwrap it with `errors.As`, then branch on `StatusCode`:
-
-```go
-_, err := client.Messages.New(ctx, params)
-if err != nil {
-    var apierr *anthropic.Error
-    if errors.As(err, &apierr) {
-        switch apierr.StatusCode {
-        case 404:
-            // bad model ID / resource
-        case 429:
-            // back off and retry
-        default:
-            // other API error — apierr.StatusCode, apierr.RequestID
-        }
-    } else {
-        // transport-level error (*url.Error wrapping *net.OpError, etc.)
-    }
-}
-```
-
-### Error `.type` Field
-
-All `APIStatusError` subclasses now expose a `.type` property (Python: `.type`, TypeScript: `.type`, Java: `.errorType()`, Go: `.Type()`, Ruby: `.type`, PHP: `.type`) that returns the API error type string (e.g., `"invalid_request_error"`, `"authentication_error"`, `"rate_limit_error"`, `"overloaded_error"`). Use this for programmatic error classification when you need finer granularity than the HTTP status code — for example, distinguishing `"billing_error"` from `"permission_error"` (both map to 403).
-
-```python
-except anthropic.APIStatusError as e:
-    if e.type == "rate_limit_error":
-        # handle rate limiting
-    elif e.type == "overloaded_error":
-        # handle overload
-```