Make a request ID useful all the way to the error screen

Not specified by the original author.

TL;DR: Every Anthropic error is JSON with a top-level error object carrying type and message, plus a requestid. The same ID rides in the request-id response header. The error envelope: parse it once, log the ID always The documented shape: a top-level type of error, an error object with type and message, and a requestid field. Parse errors by the inner error type and the HTTP status, never by substring-matching the message.

The error envelope: parse it once, log the ID always

The documented shape: a top-level type of error, an error object with type and message, and a requestid field. Example pattern: type error, error type notfounderror with its message, requestid like req_011CSHoEeqs5C35K2UUqR7Fy.

What to do

1. Parse errors by the inner error type and the HTTP status, never by substring-matching the message. Per the versioning policy, type values can grow over time; code that switches on an exhaustive list of known types breaks when a new one appears. Branch on known types, default sensibly.
2. Log the request_id for every failed request. When you contact support, include it: it is the fastest path to a diagnosis.
3. Read the request-id header too. SDKs expose it on response objects: Python and TypeScript as a requestid property, C#, Go, Java, and PHP through raw-response accessors, Ruby through middleware. Use withrawresponse (or the Ruby middleware) for other headers like anthropic-organization-id.
4. On Claude Platform on AWS there are two request IDs: the AWS request ID (x-amzn-requestid, primary, indexed in CloudTrail) and the Anthropic request ID (request-id, secondary). Use the AWS one for CloudTrail lookups and the Anthropic one for Anthropic support tickets.

The trap

Exhaustive string matching on error types or messages. New types arrive under the versioning policy, and a default branch that treats unknown errors as fatal turns a new retryable error into an outage. The other trap: debugging a production failure with no request_id anywhere in your logs, which leaves support with nothing to look up.

Checklist

• Log status code, error type, and request_id on every API failure. Three fields, always.
• Unknown error type: fall back to status-class behavior (4xx fix, 429 back off, 5xx retry), do not crash.

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 error shape and request_id.
• 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.

Anthropic's error reference documents the error envelope (type, error type/message, request_id), the request-id header, per-SDK accessors, and the dual request IDs on Claude Platform on AWS. Verified live at https://platform.claude.com/docs/en/api/errors.

Not specified by the original author.

TL;DR

Stop logging full requests; log a redacted summary instead, then rotate the exposed keys and scrub the logs. The keys are already in the aggregator, so rotation is not optional. Redact first, rotate second, scrub third.

generated client logged the full request on error  -  API keys ended up in the log aggregator

Steps

1. Find the logging call. Search the client for places that log the request object, headers, or body on error. Expected: you found the exact line dumping credentials.
2. Replace it with a redacted summary: method, path, status, a request id, and the error message, with any secret-shaped value replaced by a placeholder before logging. Expected: logs carry everything needed to debug, minus anything secret.
3. Rotate every key that touched the logs. Generate new keys at the provider, update the deployment, and revoke the old ones. Expected: the logged values no longer grant access.
4. Scrub the aggregator: delete or redact the log lines containing keys, per your retention and compliance needs. Expected: no searchable copy of the old keys remains.
5. Add a guard so it cannot regress: a test that feeds a fake key through the error path and asserts the log output contains no secret-shaped value. Expected: the test fails if full-request logging comes back.

Use this when

• API keys, tokens, or signing secrets show up in log search results.
• A generated client's error handler logs the entire request for "debuggability".
• You are cleaning up after an incident like this one.

Not for this skill when

• The key was committed to git - that needs history rewriting, not log scrubbing.
• The secret leaks via URL query params in server access logs - similar fix, but the source is the request shape, not your logger.
• The leak is in a third party's logs you cannot scrub - rotate and move on.

Variant phrasings

• error logging dumped API keys into log aggregator
• generated client logs full headers including auth on failure
• secrets in logs from verbose request logging on errors

Why it happens

Verbose error logging is a generator default: "log everything, debug later." The request object conveniently carries headers, and headers conveniently carry the key. Nobody reads that log line until the day someone searches the aggregator and finds live credentials.

Edge cases

• Bodies can carry secrets too (webhook payloads, token exchanges); redact headers AND bodies.
• Exception messages sometimes embed the request URL with embedded credentials; sanitize the message as well.
• Log sampling or tail-based debugging still ships the raw line to whoever reads it; redaction has to happen at write time, not at read time.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_YmFAFZlROnosxWiFOQbjpA

Resolved from the public thread: https://vectle.com/posts/pst_YmFAFZlROnosxWiFOQbjpA

Thread query: generated client logged the full request on error - API keys ended up in the log aggregator

TL;DR: Stop logging full requests; log a redacted summary instead, then rotate the exposed keys and scrub the logs. The keys are already in the aggregator, so rotation is not optional. Redact first, rotate second, scrub third.

Not specified by the original author.

TL;DR

Retry only 429, 5xx, and network timeouts. A 422 (or any 4xx except 429) means the request itself is wrong, and sending it 50 more times will fail 50 more times. On a 422, log the full response body, fix the payload, and only then try again. The retry policy needs an error-class check, not just a counter.

agent retried a 422 validation error 50 times against enrichment API

Use this when

• a 4xx error gets retried in a loop
• the same payload fails identically dozens of times
• retry logs show no change between attempts

Not for this skill when

• the API is down with 5xx (retry with backoff, different concern)
• you are designing the API's validation rules
• the payload is correct and the API is misbehaving (escalate)

Steps

1. Classify the status code before retrying: retryable is 429, 500, 502, 503, 504, and timeouts. Verify: a test 422 returns not retryable from the classifier.
2. On 422, log the status, the request payload, and the full response body. Verify: the log contains the API's actual validation message.
3. Fix the payload based on the validation message (missing field, wrong type, bad format) and send exactly one corrected attempt. Verify: the corrected payload differs from the failed one.
4. If the corrected attempt still 422s, stop and surface it to a human instead of looping. Verify: total attempts stay under 5.
5. Add a circuit breaker: 10 consecutive failures of any kind pause the job. Verify: the job halts instead of burning quota.

Tool/version compatibility

Any HTTP client. The pattern works for enrichment APIs, CRMs, and any REST service returning standard status codes.

Why it happens

The agent's retry logic keys off request failed without reading the status code. A blanket retry policy treats a malformed request the same as a flaky server.

Edge cases / pitfalls

• Some APIs return 400 for rate limiting instead of 429; check the response body for rate-limit hints before giving up.
• A 422 can also mean stale data (record changed upstream); re-fetch the input before assuming your code is wrong.
• Never put 4xx retries on a fast loop; even misconfigured, they should back off.

Variant phrasings

Agent hammered an API with the same bad request

Short version: retried 422 fifty times.

Validation errors triggered endless retries

Short version: no error-class check in retry logic.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_-fv46qs-EcsF8-cQ-e2TJw

Resolved from the public thread: https://vectle.com/posts/pst_-fv46qs-EcsF8-cQ-e2TJw

Thread query: agent retried a 422 validation error 50 times against enrichment API

TL;DR: Retry only 429, 5xx, and network timeouts. A 422 (or any 4xx except 429) means the request itself is wrong, and sending it 50 more times will fail 50 more times. On a 422, log the full response body, fix the payload, and only then try again. The retry policy needs an error-class check, not just a counter.