docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

[janiussyafiq]

Summary

Closes#351. PR #343 changed proxy errors on POST /v1/messages to emit an Anthropic-shape envelope ({type:"error", error:{type, message}}) instead of the OpenAI envelope used by every other proxy endpoint. Four documentation pages still described the OpenAI envelope as universal across the proxy — a Claude SDK developer writing client-side error handling against any of these four pages would parse against the wrong shape and see the wrong type strings from /v1/messages. This PR documents /v1/messages as the exception and enumerates the gateway's emitted 9-string subset of Anthropic's 10 canonical error types.

Doc-only diff (4 files, +6/-2). No code, schemas, configs, or test fixtures touched.

Changes

File	Change
docs/integration/anthropic-messages.md:58	## Error Shape body rewritten. Removed the incorrect "Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope" claim. New body describes the Anthropic-shape envelope, lists the gateway's 9-string subset with per-status mappings, notes the 408→timeout_error unreachability, and cross-links the canonical 10-type list at https://platform.claude.com/docs/en/api/errors.
docs/integration/errors-and-retries.md (between L9 and L11)	Exception callout inserted between the page lede ("Use this page to understand what a caller should do…") and the ## Error Envelope heading: **Exception:** errors on POST /v1/messages use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape] for the shape and the gateway's emitted type-string subset.
docs/reference/headers-and-error-codes.md (after L34)	Exception note appended after the existing Proxy Error Types section's closing sentence. Names the OpenAI-vs-Anthropic-shape split as load-bearing, enumerates the Anthropic-shape type strings the gateway emits, notes the 408→timeout_error unreachability, and cross-links the integration page for the per-status mapping and wider-canonical context.
docs/quickstart/anthropic-sdk.md:115	Verification Notes bullet rewritten in concise quickstart form. Replaced the incorrect "errors still use the gateway's OpenAI-compatible proxy error envelope" claim with the Anthropic-shape envelope description, the 8 reachable type strings, the billing_error fold-in note, and cross-links to the Errors and Retries integration page + Anthropic's Errors documentation.

Net diff: 4 files, +6 / -2. Source: git diff --stat.

Test plan

Doc-only diff — no .rs files, schemas, configs, or test fixtures touched. The cargo trio was still run end-to-end as the canonical pre-merge gate. Used -j 2 for parallel compile cap per the locked workaround on this 8 GB VPS.

• cargo fmt --check — PASS (exit 0).
• cargo clippy --workspace --all-targets -j 2 -- -D warnings — PASS (exit 0, 0.70s incremental, no warnings).
• cargo test --workspace -j 2 — PASS (exit 0; 33 suites all green; 1067 tests passed, 0 failed, 3 ignored).
• grep -rln <each affected page> tests/e2e/ for all 4 pages returns empty. pnpm test under tests/e2e/ is not applicable for this diff. The Anthropic-shape envelope contract this PR documents IS exercised by tests/e2e/src/cases/anthropic-messages-error-envelope-e2e.test.ts (added in fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343) — that suite tests the envelope shape and the per-status type strings the gateway emits.

cargo clippy tail

 Finished `dev` profile [unoptimized + debuginfo] target(s) in 0.70s

cargo test summary

33 test-suite-result lines, all 'ok'. Aggregate: 1067 tests passed, 0 failed, 3 ignored across the workspace.

Affected pages

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/reference/headers-and-error-codes.md
• docs/quickstart/anthropic-sdk.md

Pre-merge-check verification log

Issue #351 called out three pre-merge checks. All three resolved as follows:

1. Re-grep the consumer at PR-time HEAD. Verified crates/aisix-proxy/src/error.rs:320-338 on current origin/main HEAD 2c1d485:

   fnanthropic_kind_from_status(status:StatusCode) -> &'staticstr{match status.as_u16(){400 | 422 => "invalid_request_error",401 => "authentication_error",403 => "permission_error",404 => "not_found_error",413 => "request_too_large",429 => "rate_limit_error",503 => "overloaded_error",// 408 timeout maps to `timeout_error` in the SDK literal; the// gateway doesn't emit 408 today (timeouts surface as 502 via// the Bridge), but the case is kept for completeness.408 => "timeout_error",// 500 / 502 / 504-599 plus anything outside the recognised// codes fall back to `api_error` — the SDK literal's catch-all// for generic upstream / server faults.
   _ => "api_error",}}

   ✓ 9-string subset documented in the issue body matches verbatim. The 408→timeout_error "in the map but unreachable" framing is supported by the code comment.

2. Verify the cited Anthropic spec URL.https://platform.claude.com/docs/en/api/errors resolves and lists the canonical 10-type set (invalid_request_error, authentication_error, billing_error, permission_error, not_found_error, request_too_large, rate_limit_error, timeout_error, api_error, overloaded_error). ✓ Match — the gateway maps 9 of these 10 explicitly; billing_error is folded into api_error and called out as the one omission in each affected section.

3. Editorial choice for finding feat(core): Model, ApiKey, RateLimit entities + JSON Schema validators #3. Used the inline exception-note form (appended after the existing "These values appear in the proxy's OpenAI-compatible error envelope." sentence) rather than a parallel sub-section. Rationale: the existing Proxy Error Types section is already a compact list; an inline note preserves its scan-rate and gives the OpenAI/Anthropic distinction equal weight in the prose without restructuring the page.

4. CLAUDE.md §7 wire-format claim — upstream-spec citation. This PR touches a wire-format claim against an upstream provider. Anthropic's Errors documentation (https://platform.claude.com/docs/en/api/errors) is cited in each of the four affected sections per §7. Reference-implementation citation is N/A here — LiteLLM and Portkey do not implement this gateway's subset-vs-canonical relationship (they pass the upstream's error shape through unchanged or normalise to their own taxonomy), so they are not authoritative for the doc claim. The runtime consumer (anthropic_kind_from_status() in aisix-proxy/src/error.rs) is the authoritative ref-impl in this case, and is cited in each section.

Coexistence with PR #350

PR #350 (Wave-2 sibling, docs/tutorials/enable-response-caching.md cache-fingerprint correction) touches a disjoint file from this PR. No git merge-tree collision check needed.

References

• docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs #351 — docs: document /v1/messages Anthropic-shape error envelope exception across error/integration docs (this PR closes it)
• fix(proxy): /v1/messages emits Anthropic-shape error envelope (#336) #343 — fix(proxy): /v1/messages emits Anthropic-shape error envelope (the runtime change that made these 4 doc pages stale)
• docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) #350 — docs: correct cache-fingerprint description on enable-response-caching tutorial (caller key is excluded) (companion Wave-2 PR, disjoint files)
• docs: fix new-developer onboarding gaps across overview, quickstart, and configuration pages #326 — established the consumer-trace discipline for Status-column rows
• docs: add glossary page + first-use linking + quickstart shell-mechanics framing + polish #344 — extended consumer-trace discipline to inline mini-defs and user-facing warnings
• docs: correct configuration reference inaccuracies across admin-api, api-keys, caching, and models pages #348 — applied consumer-trace discipline across the configuration reference cluster
• docs: rebuild customer-facing docs across overview, config, cloud, ops, reference, and tutorials #249 — the docs rebuild that produced these 4 pages in their current form

Upstream spec citation (per CLAUDE.md §7)

• Anthropic Errors documentation (canonical 10-type list): https://platform.claude.com/docs/en/api/errors

Summary by CodeRabbit

• Documentation
  • Clarified that the Messages endpoint returns an Anthropic-shaped error envelope (type + error object) and linked this behavior across integration, quickstart, and reference docs.
  • Enumerated gateway-emitted error type strings and their HTTP groupings, noting omitted/unreachable types (e.g., internal timeouts surfaced differently; canonical billing error folded into api_error).
  • Documented that passthrough endpoints forward upstream errors verbatim.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 524bce8b-a294-4169-876c-a1955512fda0

📥 Commits

Reviewing files that changed from the base of the PR and between 123ccf2 and 18dbc61.

📒 Files selected for processing (4)

• docs/integration/anthropic-messages.md
• docs/integration/errors-and-retries.md
• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md

✅ Files skipped from review due to trivial changes (4)

• docs/quickstart/anthropic-sdk.md
• docs/reference/headers-and-error-codes.md
• docs/integration/errors-and-retries.md
• docs/integration/anthropic-messages.md

---

📝 Walkthrough

Walkthrough

Documentation across four pages is updated to clarify that the POST /v1/messages endpoint returns Anthropic-shaped error envelopes instead of OpenAI-compatible formats. The changes specify the exact error type strings emitted by the gateway, map them to HTTP status codes, and note unreachable and absent error types.

Changes

Anthropic Error Envelope Documentation

Layer / File(s)	Summary
Error envelope specification and reference docs/reference/headers-and-error-codes.md, docs/integration/anthropic-messages.md	Reference docs clarify that OpenAI-shaped error envelopes apply to all proxy endpoints except POST /v1/messages. Anthropic Messages integration guide replaces prior statements with detailed Anthropic error envelope structure ({type:"error", error:{type, message}, request_id:"req_..."}), emitted error type strings (invalid_request_error, authentication_error, api_error, etc.), and notes on unreachable timeout_error and absent billing_error.
Integration and SDK guidance docs/integration/errors-and-retries.md, docs/quickstart/anthropic-sdk.md	Errors-and-retries doc adds an exception note that POST /v1/messages uses Anthropic-shaped envelopes with an emitted type subset instead of the shared OpenAI-compatible envelope. Anthropic SDK quickstart replaces prior OpenAI envelope reference with Anthropic envelope structure details and documentation links for Claude SDK users.

🎯 1 (Trivial) | ⏱️ ~3 minutes

---

Note

🎁 Summarized by CodeRabbit Free

Your organization has reached its limit of developer seats under the Pro Plan. For new users, CodeRabbit will generate a high-level summary and a walkthrough for each pull request. For a comprehensive line-by-line review, please add seats to your subscription by visiting https://app.coderabbit.ai/login.If you believe this is a mistake and have available seats, please assign one to the pull request author through the subscription management page using the link above.

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[Copilot]

Pull request overview

Updates documentation to correctly describe that POST /v1/messages is an exception to the gateway’s default OpenAI-style proxy error envelope, and to document the Anthropic-style error envelope and the gateway’s emitted Anthropic error-type subset for Claude SDK users.

Changes:

• Rewrites the Anthropic Messages integration doc’s “Error Shape” section to describe the Anthropic-style envelope and type mappings.
• Adds an exception callout to the Errors and Retries integration page pointing /v1/messages readers to the Anthropic error shape details.
• Appends an exception note to the Headers and Error Codes reference and updates the Anthropic SDK quickstart verification notes accordingly.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 4 comments.

File	Description
docs/integration/anthropic-messages.md	Updates /v1/messages error-envelope documentation to Anthropic-shape with type mapping notes.
docs/integration/errors-and-retries.md	Adds a top-of-page exception callout for /v1/messages error envelope shape.
docs/reference/headers-and-error-codes.md	Adds an exception note clarifying /v1/messages uses a different error envelope/type taxonomy.
docs/quickstart/anthropic-sdk.md	Updates quickstart verification notes to reflect Anthropic-shape errors on /v1/messages.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.