Anthropic error-envelope parity matrix
Compare Anthropic-compatible error responses, headers, and documented differences
This matrix compares nexus /anthropic/* error responses against live Anthropic Messages API behavior for the common failure set exercised by certification. Status codes and error.type values are the SDK-facing contract.
| Condition | HTTP status | error.type |
Nexus behavior | Anthropic reference | Notes |
|---|---|---|---|---|---|
| Missing/invalid nexus key | 401 | authentication_error |
Matches | Matches | Accepts x-api-key or Authorization: Bearer |
Missing max_tokens |
400 | invalid_request_error |
Matches | Matches | Not defaulted on the native edge |
| Unknown model / route resolution failure | 400 | invalid_request_error |
Matches | Matches | Registry-owned reject |
| Malformed JSON body | 400 | invalid_request_error |
Matches | Matches | |
SDK echo fields on replayed blocks (citations, parsed_output, caller) |
— | — | Stripped before upstream | N/A | Prevents upstream 400 on streamed tool follow-ups |
| Policy deny | 403 | permission_error |
Matches | Matches | Includes x-nexus-request-id when scoped |
Unknown /anthropic/* route |
404 | not_found_error |
Matches | Matches | Fallback handler on the Anthropic router |
| Gateway rate limit | 429 | rate_limit_error |
Matches | Matches | Includes Retry-After (delta-seconds, same as OpenAI edge) |
| Upstream 429 | 429 | rate_limit_error |
Matches | Matches | Preserved via UpstreamStatus |
| Upstream 529 | 529 | overloaded_error |
Matches | Matches | Preserved via UpstreamStatus |
| Upstream 400 | 400 | invalid_request_error |
Matches | Matches | Body message forwarded when JSON |
| Wallet / budget cap | 400 | invalid_request_error |
Matches | Matches | Anthropic uses 400 for credit balance, not 402 |
| Internal / all attempts failed | 500 | api_error |
Matches | Matches | Includes x-nexus-request-id when scoped |
| Mid-stream upstream failure | 200 SSE → event: error |
api_error |
Matches | Matches | In-band error event, not OpenAI [DONE] |
Headers
Section titled “Headers”| Header | Success responses | Error responses | Notes |
|---|---|---|---|
x-nexus-request-id |
Present | Present when a request id is assigned (request-scoped errors) | Stable correlation id for analytics |
anthropic-version (inbound) |
Accepted, ignored at edge | Accepted | Upstream Anthropic calls set their own version |
Retry-After |
— | Present on gateway 429 | Value is the retry window in whole seconds (string), rounded up |
Upstream anthropic-ratelimit-* |
Not forwarded | Not forwarded | Nexus emits its own rate-limit surface |
Divergences
Section titled “Divergences”None unexplained for the matrix above. Upstream provider rate-limit headers are not forwarded because nexus terminates auth and applies its own limits before upstream calls complete.
Certification date: 2026-06-14. Pinned SDK versions: spec/anthropic-sdk-provenance.json.