fix(proxy): normalise upstream error.type to DP taxonomy, keep code/param verbatim (#327)

[moonming]

Summary

Fixes #327. PR #323 over-corrected by preserving upstream's error.type verbatim — this broke the stable "upstream_error" contract that dp-upstream-error-live.spec.ts:152 already pins, and leaked upstream-private taxonomy (upstream_test_fixture, AccessDeniedException, authentication_error, etc.) to customers.

Contract correction

Field	Source	Why
error.type	DP taxonomy: "upstream_error"	Stable, customer-SDK-actionable, hides upstream zoo
error.message	upstream verbatim (4xx) / canned (5xx)	Human-readable, already correct
error.code	upstream verbatim or derived per-wire	SDK retry branches on this — preservation from #322 stays
error.param	upstream verbatim	Tells client which field caused the error — preservation from #322 stays

Customer SDKs branch on error.type == "upstream_error" for upstream-class detection and on error.code for granular retry routing.

Implementation

• error_translate::render_openai_envelope: hardcodes kind to a new UPSTREAM_ERROR_TYPE constant ("upstream_error").
• Translation tables collapse from (String, Option<String>) to Option<String> — the per-wire OpenAI type half is now uniformly "upstream_error", so the tables only carry the derived OpenAI string code.
• 5xx, UpstreamWire::Unknown, and generic-envelope paths already emit "upstream_error" — this commit just makes the 4xx path consistent.

Reference impl divergence (CLAUDE.md §7)

The established gateway impls in this space normalise upstream taxonomy too — LiteLLM maps to a closed set of Python exception classes, Portkey emits its own stable type enum. Choosing a single DP token ("upstream_error") rather than a closed OpenAI-vocabulary set (invalid_request_error, rate_limit_exceeded, server_error) is more conservative — it sidesteps the question of how Bedrock's AccessDeniedException should map onto OpenAI's invalid_request_error vs authentication_error, since the customer just needs "upstream broke; check code for granularity."

Test plan

• cargo check --workspace --all-targets clean
• cargo clippy --workspace --all-targets clean
• cargo fmt --check clean
• cargo test --workspace — all tests green
• 22 error_translate::tests updated: body.kind always "upstream_error", code assertions unchanged
• 3 affected integration tests in aisix-proxy::tests updated and renamed to reflect the corrected contract:
  • upstream_openai_4xx_forwards_code_and_param_but_normalises_type_per_issue_327 (was ..._forwards_full_envelope_per_issue_322)
  • upstream_anthropic_400_normalises_type_to_upstream_error (was ..._passes_through_with_openai_envelope)
  • upstream_anthropic_rate_limit_derives_openai_rate_limit_exceeded_code (was ..._translates_to_openai_rate_limit_exceeded)
• dp-upstream-error-live.spec.ts:152 should go back to green once :dev image is rebuilt with this PR merged.
• AISIX-Cloud matrix spec tightening (adapter-openai-overrides-live.spec.ts:634 from upstream_test_fixture to upstream_error) is the issue author's follow-up.

Closes #327

Summary by CodeRabbit

• Bug Fixes
  • Standardized upstream service error responses to use consistent error type formatting across all provider services, preventing provider-specific error taxonomy from being exposed to client applications.
  • Enhanced error code mapping to improve SDK compatibility and ensure proper retry routing behavior across integrated providers.

[coderabbitai]

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Free

Run ID: 443cdddd-c528-4f52-95ac-29328f6b5e15

📥 Commits

Reviewing files that changed from the base of the PR and between 1a744ee and 0fe40fc.

📒 Files selected for processing (2)

• crates/aisix-proxy/src/error_translate.rs
• crates/aisix-proxy/src/lib.rs

---

📝 Walkthrough

Walkthrough

This PR normalizes upstream error type handling in the proxy: error.type is always set to the DP-stable "upstream_error" token for upstream-originated 4xx errors, while error.code is intelligently derived via provider-specific helpers that map upstream taxonomies to OpenAI-compatible strings, with fallback preservation of upstream codes when derivation is unavailable.

Changes

Error type normalization and code derivation

Layer / File(s)	Summary
Documentation and envelope rendering refactoring crates/aisix-proxy/src/error_translate.rs	Module documentation updated to describe DP-stable error type normalization. The render_openai_envelope function refactored to always set kind to fixed "upstream_error" token and compute derived OpenAI code via per-upstream match logic that prefers derived codes for non-OpenAI wires while preserving upstream codes for OpenAI same-wire.
Error code derivation helpers crates/aisix-proxy/src/error_translate.rs	Introduced UPSTREAM_ERROR_TYPE constant, updated generic envelope builder, and new derive_anthropic_code, derive_bedrock_code, derive_vertex_code, and derive_azure_code functions returning Option<String> for provider-specific OpenAI-compatible code mappings; Azure falls back to upstream code when derivation returns None.
Anthropic and Bedrock error handling tests crates/aisix-proxy/src/error_translate.rs	Updated and added unit tests for Anthropic error kinds and Bedrock throttling to assert kind == "upstream_error" while validating derived code values (including None for unmapped kinds).
Bedrock, Vertex, and Azure error mapping tests crates/aisix-proxy/src/error_translate.rs	Expanded tests for Bedrock quota/validation/access errors, Vertex gRPC status-code mappings, and Azure DeploymentNotFound to verify normalized kind and provider-specific derived code values.
Azure/OpenAI compatibility and same-wire preservation tests crates/aisix-proxy/src/error_translate.rs	Tests for Azure content-policy violation derivation, Azure OpenAI-compatible code fallback behavior, OpenAI same-wire preservation of both code and param with normalized kind, and missing-parsed-message derived code assertion.
Cross-provider contract tests in lib.rs crates/aisix-proxy/src/lib.rs	Integration-level tests verifying that OpenAI upstream 4xx and Anthropic 400/rate-limit errors enforce normalized error.type == "upstream_error" at the proxy boundary while preserving granular error.code and error.param for SDK retry branching and Anthropic→OpenAI code derivation.

🎯 3 (Moderate) | ⏱️ ~25 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

This PR corrects an over-correction from #323: while error.code and error.param are still preserved verbatim from upstream (preserving #322's SDK retry-routing fix), error.type is now normalized to the DP-stable "upstream_error" token across all wires/paths, so upstream-private taxonomies (upstream_test_fixture, AccessDeniedException, authentication_error, etc.) no longer leak to customers. The translation tables in error_translate.rs are collapsed from (type, code) pairs to a single derived code.

Changes:

• Hardcode kind = "upstream_error" in render_openai_envelope; introduce UPSTREAM_ERROR_TYPE constant.
• Rename translate_* → derive_*_code and return Option<String> only (the OpenAI-shape code).
• Update unit and integration tests + their docstrings/names to assert the corrected contract.

Reviewed changes

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

File	Description
crates/aisix-proxy/src/error_translate.rs	Drop per-wire type derivation; emit DP-stable upstream_error and only derive OpenAI code. Update module doc and tests.
crates/aisix-proxy/src/lib.rs	Rename/retighten 3 integration tests to assert type == "upstream_error" while keeping code/param preservation assertions.

---

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

[moonming]

Audit completed — verdict: merge, no HIGH/MEDIUM findings.

Two LOW findings:

• Streaming SSE error frames bypass 5xx redaction — pre-existing gap, not introduced by this PR but surfaced by the audit. Filed as bug(proxy): streaming SSE error frames bypass 5xx upstream-message redaction #329 for separate work.
• UpstreamWire::Unknown arm in render_openai_envelope is dead in production (caller gates it off). Left defensive — no action.

Per CLAUDE.md §8 merge gate: ready when CI passes.

[moonming]

Follow-up on the audit's LOW-1: traced the path, not a real bug. BridgeError::UpstreamStatus is only constructed pre-stream (via map_http_error), and the stream itself only yields Transport/UpstreamDecode whose Display impls don't carry upstream body content. Closed #329 with the trace.