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

docs/integration/anthropic-messages.md

@@ -55,7 +55,7 @@ The caller still uses the gateway API key, not the upstream Anthropic provider k
 
 ## Error Shape
 
-Even on the Anthropic-style endpoint, proxy errors still use the gateway's OpenAI-compatible error envelope so client-side proxy handling stays consistent.
+Proxy errors on `/v1/messages` use the Anthropic-shape envelope `{type:"error", error:{type, message}, request_id:"req_..."}` — Claude SDKs expect this shape from the Anthropic wire. The error type strings the gateway currently emits are `invalid_request_error` (400, 422), `authentication_error` (401), `permission_error` (403), `not_found_error` (404), `request_too_large` (413), `rate_limit_error` (429), `overloaded_error` (503), and `api_error` (all other 4xx/5xx). The mapping also contains `timeout_error` for 408, but that path is currently unreachable — the gateway's internal timeouts surface as 502 via the Bridge and fold into `api_error`. The canonical Anthropic spec includes one additional type — `billing_error` (402) — that real Anthropic upstream may emit but this gateway currently folds into `api_error`; for cross-upstream-compatible client error handling, treat unknown type strings as recoverable per Anthropic's [Errors documentation](https://platform.claude.com/docs/en/api/errors).
 
 ## When To Use `/v1/messages`
 

docs/integration/errors-and-retries.md

@@ -8,6 +8,8 @@ AISIX AI Gateway uses a shared proxy error envelope across its client-facing pro
 
 Use this page to understand what a caller should do after a failed request, not just what status code was returned.
 
+**Exception:** errors on `POST /v1/messages` use the Anthropic-shape envelope instead of the OpenAI envelope — see [Anthropic Messages — Error Shape](anthropic-messages.md#error-shape) for the shape and the gateway's emitted type-string subset.
+
 ## Error Envelope
 
 The proxy returns an OpenAI-compatible error body:

docs/quickstart/anthropic-sdk.md

@@ -112,7 +112,7 @@ If you depend on advanced Anthropic-only content block behavior, prefer models w
 - `401` means the AISIX caller API key is missing or invalid
 - `403` means the key cannot access the requested model alias
 - `404` means the model alias is not present in the current snapshot
-- errors still use the gateway's OpenAI-compatible proxy error envelope
+- errors on `/v1/messages` use the Anthropic-shape envelope your Claude SDK already expects: `{type:"error", error:{type, message}, request_id:"req_..."}`. The gateway currently emits `invalid_request_error`, `authentication_error`, `permission_error`, `not_found_error`, `request_too_large`, `rate_limit_error`, `overloaded_error`, and `api_error` (catch-all). For the full Anthropic-canonical type list (one type — `billing_error` for 402 — is folded into `api_error` by this gateway), see the [Errors and retries integration page](../integration/errors-and-retries.md) and Anthropic's [Errors documentation](https://platform.claude.com/docs/en/api/errors)
 
 ## Troubleshooting
 

docs/reference/headers-and-error-codes.md

@@ -33,6 +33,8 @@ Current proxy error `type` values include:
 
 These values appear in the proxy's OpenAI-compatible error envelope.
 
+Note: this section describes the OpenAI-shape error envelope used by every proxy endpoint **except** `POST /v1/messages`. The `/v1/messages` endpoint uses the Anthropic-shape envelope `{type:"error", error:{type, message}, request_id:"req_..."}` and emits a different set of type strings — `invalid_request_error` (400/422), `authentication_error` (401), `permission_error` (403), `not_found_error` (404), `request_too_large` (413), `rate_limit_error` (429), `overloaded_error` (503), and `api_error` (all other 4xx/5xx). The mapping also includes `timeout_error` for 408 but that path is currently unreachable. See the [Anthropic Messages integration page](../integration/anthropic-messages.md#error-shape) for the per-status mapping and notes on the wider Anthropic-canonical type set.
+
 ## Proxy Status Boundaries
 
 - `400` invalid request