claude-code - 💡(How to fix) Fix [DOCS] Policy refusal errors missing Request ID guidance in error reference [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/errors

Section/Topic

"Find your error" and "Report an error" on the Error reference page

Current Documentation

The page currently frames itself as the place to look up Claude Code runtime errors, but it does not document policy refusal errors or mention Request IDs:

This page lists runtime errors Claude Code displays and how to recover from each one, plus what to check when responses seem off without an error.

Message	Section
API Error: 500 ... Internal server error	Server errors
API Error: Repeated 529 Overloaded errors	Server errors
Request timed out	Server errors, or Network if the message mentions your internet connection
...
API Error: 400 due to tool use concurrency issues	Request errors
Responses seem lower quality than usual	Response quality

Later, the support guidance says:

If an error is not listed here or the suggested fix does not help:

• Run /feedback inside Claude Code to send the transcript and a description to Anthropic.
• Run /doctor to check for local configuration problems
• Check status.claude.com for active incidents
• Search existing issues on GitHub

What's Wrong or Missing?

The Error reference page does not document policy refusal errors as a distinct runtime error case, and it does not explain that refusal messages now include the API Request ID for support debugging in v2.1.129.

That leaves two gaps:

A. Missing refusal-error coverage

Users who hit a policy refusal cannot find that message in the runtime error index, even though the page claims to cover Claude Code runtime errors.

B. Missing Request ID support guidance

The page tells users to use /feedback or contact support, but it does not tell them to include the API Request ID now shown in refusal errors, which is the key detail that makes those reports easier to investigate.

Suggested Improvement

Add a new refusal/policy error section to the Error reference page and include the new Request ID support workflow.

Suggested content:

Policy refusal error

Claude rejected the request for policy reasons.

[example refusal error message including the API Request ID]

What to do:

• Review the refusal explanation shown in the error message
• If you contact Anthropic support or file /feedback, include the API Request ID from the refusal message
• Retry only after changing the request if the refusal explains a prompt/content policy problem

If the exact message text varies by surface, the page could document the pattern instead of one rigid string, but it should still call out that the API Request ID is now included and should be preserved in support reports.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 2 Claude Code sections affected, with one relevant platform cross-reference

Relevant changelog context: this behavior changed in v2.1.129, so the Claude Code error-reference page should mention that refusal messages now surface the API Request ID for debugging and support.