502 `provider_unavailable` errors from OpenRouter are not retried, causing subagent/session aborts

[tim-mohrbach-ikigai]

Description

When OpenRouter returns a 502 error (e.g., Network connection lost, provider_unavailable), OpenCode does not retry the request. Instead, the message is marked as errored and the entire step — including any in-progress tool calls — is aborted with Tool execution aborted / interrupted: true.

This is particularly destructive for subagent sessions: the subagent dies completely, all work in that step is lost, and the parent session may also lose its connection waiting for the task result.

What I've Noticed

The 502 error arrives as an UnknownError (not APIError) with a JSON body:

{"code":502,"message":"Network connection lost.","metadata":{"error_type":"provider_unavailable"}}

In packages/opencode/src/session/retry.ts, the retryable() function has logic to handle this:

// Line ~62
if (code.includes("exhausted") || code.includes("unavailable")) {
  return "Provider is overloaded"
}

However, code is extracted as:

const code = typeof json.code === "string" ? json.code : ""

The issue: json.code is 502 (a number), not a string. So typeof json.code === "string" is false, and code becomes "". The code.includes("unavailable") check never matches.

Additionally, the string "unavailable" appears in json.metadata.error_type ("provider_unavailable"), which is never inspected.

Evidence

From my session database, I've logged 19 instances of 502 Network connection lost errors across April 9-14, affecting both anthropic/claude-sonnet-4.6 (16 times) and z-ai/glm-5.1 (3 times). None were retried.

Example error from the DB:

{
  "name": "UnknownError",
  "data": {
    "message": "{\"code\":502,\"message\":\"Network connection lost.\",\"metadata\":{\"error_type\":\"provider_unavailable\"}}"
  }
}

A second variant exists:

{
  "name": "UnknownError",
  "data": {
    "message": "{\"code\":502,\"message\":\"JSON error injected into SSE stream\",\"metadata\":{\"error_type\":\"provider_unavailable\"}}"
  }
}

Proposed Change

In packages/opencode/src/session/retry.ts, around line 62, the JSON code extraction could be updated to handle numeric codes and also check metadata.error_type:

// Current:
const code = typeof json.code === "string" ? json.code : ""

// Proposed:
const code = typeof json.code === "string"
  ? json.code
  : typeof json.code === "number"
    ? String(json.code)
    : ""
const errorType = typeof json.metadata?.error_type === "string" ? json.metadata.error_type : ""

And the retryable check could be expanded:

// Current:
if (code.includes("exhausted") || code.includes("unavailable")) {
  return "Provider is overloaded"
}

// Proposed:
if (code.includes("exhausted") || code.includes("unavailable") || errorType.includes("unavailable")) {
  return "Provider is overloaded"
}
if (["502", "503", "524"].includes(code)) {
  return "Provider temporarily unavailable"
}

Impact

• 502s are transient — OpenRouter typically recovers within seconds
• Subagent sessions are killed entirely, wasting all accumulated context and tokens
• The parent session may also abort, compounding the waste
• A simple retry with backoff would recover most of these failures automatically

Related Issues

• write tool sometimes has a "request was aborted" result #268 — write tool "request was aborted" (closed but problem persists)
• Tool execution aborted #1100 — Tool execution aborted from truncated JSON input
• always stuck at “Preparing write...” #11112 — "always stuck at Preparing write..."

[github-actions]

This issue might be a duplicate of existing issues. Please check:

• Claude/Anthropic 500/502/503/504 server errors are not retried #21420: Claude/Anthropic 500/502/503/504 server errors are not retried — same root cause (5xx errors not retried), different provider
• fix: 5xx errors from non-standard providers are not retried #19203: 5xx errors from non-standard providers are not retried — very similar: non-standard/proxy providers returning 502 as non-retryable UnknownError
• fix(session): UnknownError should be retried by default #20822: UnknownError should be retried by default — directly overlaps: UnknownError (the type your 502s become) never enters retry path
• Some transient stream/rate-limit errors bypass retry and terminate sessions #21893: Some transient stream/rate-limit errors bypass retry and terminate sessions — same symptom: transient upstream errors fall through retry logic and kill the session
• Anthropic overloaded_error is not retried, halts session #20384: Anthropic overloaded_error is not retried — same pattern: a numeric/typed error field not matched by string-based retry checks

Your issue has good specificity (OpenRouter, numeric json.code, metadata.error_type path) and may warrant its own fix, but please check whether one of the above already covers the same code path before proceeding.

[tim-mohrbach-ikigai]

Thanks for the related issue links. After reviewing them, here's where this fits in:

The core problem is systemic — 5xx errors falling through to UnknownError and never being retried. This is tracked across #19203, #20822, #21420, and #19394.

Closest to landing: PR #19204 (for #19203) adds 5xx detection in fromError() by checking status/statusCode on Error objects and their JSON message bodies. It's mergeable with tests.

However, it doesn't cover our specific case. OpenRouter returns {"code":502,...} — using code instead of status/statusCode. PR #19204's JSON fallback checks obj?.status ?? obj?.statusCode but misses obj?.code. I've suggested adding code to the extraction on that PR.

If #19204 merges with that addition, this issue can be closed. Until then, the specific OpenRouter gap documented here remains — json.code is numeric (fails the typeof === "string" check in retry.ts), and metadata.error_type: "provider_unavailable" is never inspected.

[tim-mohrbach-ikigai]

Updating the status since there has been progress on PR #19204.

What PR #19204 now covers: The PR author accepted the suggestion to add obj?.code to the status extraction chain in fromError() in message-v2.ts. So if an OpenRouter 502 arrives as an unrecognised error object, it will now be classified as a retryable APIError with statusCode: 502. That part of the gap is fixed once #19204 merges.

What is still not fixed — and why this issue stays open: There is a parallel code path in retry.ts that does its own JSON parsing of UnknownError message strings. It has the same numeric code problem independently:

// retry.ts — current
const code = typeof json.code === "string" ? json.code : ""

if (code.includes("exhausted") || code.includes("unavailable")) {
  return "Provider is overloaded"
}

OpenRouter sends code as a number (502), so typeof json.code === "string" is false, code becomes "", and the "unavailable" check never fires. PR #19204 does not touch retry.ts, so this path remains broken after the PR merges.

The fix needed in retry.ts mirrors what #19204 does in message-v2.ts — handle numeric json.code and optionally check json.metadata?.error_type:

const code = typeof json.code === "string"
  ? json.code
  : typeof json.code === "number"
    ? String(json.code)
    : ""
const errorType = typeof json.metadata?.error_type === "string" ? json.metadata.error_type : ""

if (code.includes("exhausted") || code.includes("unavailable") || errorType.includes("unavailable")) {
  return "Provider is overloaded"
}
if (["502", "503", "524"].includes(code)) {
  return "Provider temporarily unavailable"
}

Keeping this issue open to track the retry.ts fix specifically.