bug(dp): upstream 4xx forwarding loses the upstream-side `error.code` field

[moonming]

Summary

Phase 1 of the E2E matrix series (#328) added a scenario asserting that an upstream 4xx response with an OpenAI-shape error envelope is forwarded as-is to the customer. The DP forwards the right status (429) and the right `error.message`, but drops the `error.code` field.

Repro

Phase 1 spec, scenario "upstream 4xx is forwarded as-is with the OpenAI-shape body intact":

```
expect: "forced_429"
received: undefined

626 | expect(err?.code, 'code preserved').toBe('forced_429');
```

mock-llm returns:
```json
{
"error": {
"message": "mock-llm forced status 429",
"type": "upstream_test_fixture",
"code": "forced_429"
}
}
```

DP forwards to customer:

• ✓ status 429
• ✓ `error.message` (preserved)
• ✗ `error.code` (dropped — assertion fails)
• ? `error.type` (not asserted)

Customer impact

OpenAI's official error envelope has 4 fields: `message`, `type`, `code`, `param`. SDKs and downstream tools (Langchain, LiteLLM-compat shims, Helicone, etc.) commonly switch on `code` to decide retry logic — `rate_limit_exceeded` vs `insufficient_quota` vs `model_not_found` all carry different recovery paths. Dropping `code` from the forwarded envelope silently downgrades every customer's retry intelligence when an upstream returns a coded 4xx.

Expected behavior

For upstream 4xx pass-through (the contract Phase 1's `error_envelope` override pins as the default), the DP should forward the upstream's error envelope verbatim — all four OpenAI fields (`message`, `type`, `code`, `param`) when present.

Test impact

Phase 1 matrix scenario currently fails on the `code` assertion. To unblock Phase 1 merge, the assertion will be loosened to a comment + issue link pointing here; once this bug is fixed, the assertion gets tightened back.

[coderabbitai]

🔗 Related PRs

#283 - chore: remove legacy DP registration [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[coderabbitai]

⚠️ Possible Duplicate Issue(s)

• https://github.com/api7/AISIX-Cloud/issues/333

🔗 Related PRs

#283 - chore: remove legacy DP registration [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[moonming]

Fix path (from a source dive — ready for someone to pick up)

The bug is in the OpenAI bridge's map_http_error not parsing the upstream OpenAI error envelope. The full {message, type, code, param} shape is dropped — only status + raw body bytes (as message) survive.

Current behavior

crates/aisix-provider-openai/src/bridge.rs lines 228-236:

async fn map_http_error(status: StatusCode, resp: reqwest::Response) -> BridgeError {
    let retry_after = aisix_gateway::parse_retry_after(resp.headers());
    let message = resp.text().await.unwrap_or_default();
    BridgeError::upstream_status_with_retry_after(
        status.as_u16(),
        truncate(&message, 1024),  // raw body → swallowed as opaque string
        retry_after,
    )
}

The entire upstream body is jammed into message. BridgeError::UpstreamStatus carries no code / type / param slots, so they're gone by the time the error envelope renders.

crates/aisix-proxy/src/error.rs lines 32-41 — ErrorBody already has code: Option<String> and param: Option<String> fields, both default None on the BridgeError path.

Suggested fix shape

1. In map_http_error, try-parse the upstream body as OpenAI's error envelope before falling back to raw text:

#[derive(serde::Deserialize)]
struct UpstreamErrorBody<'a> {
    error: UpstreamErrorInner<'a>,
}
#[derive(serde::Deserialize)]
struct UpstreamErrorInner<'a> {
    message: Option<&'a str>,
    #[serde(rename = "type")]
    kind: Option<&'a str>,
    code: Option<&'a str>,
    param: Option<&'a str>,
}

async fn map_http_error(status: StatusCode, resp: reqwest::Response) -> BridgeError {
    let retry_after = aisix_gateway::parse_retry_after(resp.headers());
    let body_bytes = resp.bytes().await.unwrap_or_default();
    let parsed: Option<UpstreamErrorBody<'_>> = serde_json::from_slice(&body_bytes).ok();

    let (message, code, param, kind) = match parsed {
        Some(p) => (
            p.error.message.unwrap_or_default().to_string(),
            p.error.code.map(str::to_string),
            p.error.param.map(str::to_string),
            p.error.kind.map(str::to_string),
        ),
        None => (
            String::from_utf8_lossy(&body_bytes).into_owned(),
            None,
            None,
            None,
        ),
    };

    BridgeError::upstream_status_with_envelope(
        status.as_u16(),
        truncate(&message, 1024),
        code,
        param,
        kind,
        retry_after,
    )
}

2. Extend BridgeError::UpstreamStatus to carry the optional fields:

UpstreamStatus {
    status: u16,
    message: String,
    code: Option<String>,
    param: Option<String>,
    kind: Option<String>,
    retry_after_secs: Option<u64>,
},

3. In crates/aisix-proxy/src/error.rs::ProxyError::IntoResponse, when the inner is Bridge(BridgeError::UpstreamStatus { code, param, kind, .. }), propagate those into ErrorBody:

ErrorBody {
    message,
    kind: kind.as_deref().unwrap_or(<DEFAULT_KIND>),
    param,
    code,
}

4. Apply the symmetric change to the Anthropic bridge (crates/aisix-provider-anthropic/src/bridge.rs) — Anthropic's error envelope shape is {type: "error", error: {type, message}}, no code / param, so map type -> kind only.

Test coverage

Coverage is already wired up. api7/AISIX-Cloud#328 (Phase 1 matrix) has a scenario upstream 4xx is forwarded as-is with the OpenAI-shape body intact that today asserts only status + message. The error.code assertion is commented out with a pointer to this issue:

// Re-enable this assertion once api7/ai-gateway#322 lands:
//   expect(err?.code, 'code preserved').toBe('forced_429');

mock-llm already returns the right fixture body when the upstream model name carries the force-status-NNN marker — see e2e/mock-llm/main.go::chatHandler lines 158-175 in the api7/AISIX-Cloud repo. So a fix here can be verified by un-commenting the assertion on the matrix PR and pushing.

Customer impact

OpenAI's error envelope has 4 fields. SDKs and downstream tools (LangChain, agent frameworks, retry libraries) commonly switch on error.code to decide retry logic — rate_limit_exceeded vs insufficient_quota vs model_not_found all carry different recovery paths. Dropping code silently downgrades every customer's retry intelligence on every coded 4xx from upstream.

Reference

Per the repo's CLAUDE.md §7 ("Reference Implementations Before Building"), check how the established multi-provider proxies handle upstream error envelope preservation — both LiteLLM and Portkey preserve error.code / error.type through their proxy layers. Worth a glance for the parsing edge cases (some upstreams emit envelope under error key, some bare; rate-limit responses sometimes pack code into headers instead of body).