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

docs/integration/anthropic-messages.md

@@ -55,7 +55,22 @@ 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}}`. Real Anthropic upstream responses also carry an optional `request_id` field; the gateway omits it.
+
+The gateway emits these `error.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)
+- `api_error` — all other 4xx/5xx (including 402, which Anthropic's canonical spec maps to `billing_error`)
+
+The map also contains `timeout_error` for 408, currently unreachable — internal timeouts surface as 502 via the Bridge.
+
+See Anthropic's [Errors documentation](https://platform.claude.com/docs/en/api/errors) for the canonical type list.
 
 ## When To Use `/v1/messages`
 

docs/integration/errors-and-retries.md

@@ -8,6 +8,11 @@ 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.
 
+**Exceptions:**
+
+- 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.
+- errors on `ANY /passthrough/:provider/*rest` are forwarded from the upstream provider verbatim after the proxy's own auth and provider resolution complete — see [Provider Passthrough](passthrough.md).
+
 ## 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 `{type:"error", error:{type, message}}` — see [Anthropic Messages — Error Shape](../integration/anthropic-messages.md#error-shape) for the gateway's emitted type strings and how they map to Anthropic's canonical set
 
 ## Troubleshooting
 

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

@@ -33,6 +33,11 @@ Current proxy error `type` values include:
 
 These values appear in the proxy's OpenAI-compatible error envelope.
 
+This list covers gateway-generated errors on the OpenAI-shape proxy endpoints. Two surfaces are exceptions:
+
+- `POST /v1/messages` — uses the Anthropic-shape envelope with its own type-string set. See [Anthropic Messages — Error Shape](../integration/anthropic-messages.md#error-shape).
+- `ANY /passthrough/:provider/*rest` — forwards the upstream provider's status code and body verbatim after proxy auth + provider resolution. See [Provider Passthrough](../integration/passthrough.md).
+
 ## Proxy Status Boundaries
 
 - `400` invalid request