feat(ai): status, code, isRetryable and retryAfterMs on AIError (#60808)

This commit is contained in:
Aiden Cline
2026-11-01 11:04:07 -06:00
committed by GitHub
Unverified
parent 288fa12843
commit 97a71f0cc6
5 changed files with 173 additions and 76 deletions
+17
View File
@@ -137,6 +137,23 @@ res.object.city
`stream` puts `object` on its `finish` event; `loop` runs tools first and puts it on the loop's `finish`. A
decode failure is an `AIError` whose `partial` holds the response.
### Errors
Every failure is an `AIError`. `reason._tag` names the kind (`RateLimit`, `InvalidRequest`, `Transport`, ...), and
getters read the common fields without digging into `reason` or the raw body:
```ts
try {
await ai.generate({ model, prompt: "Hi" })
} catch (error) {
if (!(error instanceof AIError)) throw error
error.status // HTTP status, when the failure came from a response
error.code // provider error code such as "model_not_found", when known
error.isRetryable // whether sending the same request again may succeed
error.retryAfterMs // delay the provider asked for, when known
}
```
### Raw provider events
Set `includeRaw: true` on a request to also receive every provider frame as `{ type: "raw", data }`, in order and
+2 -75
View File
@@ -11,8 +11,7 @@ import {
type HttpContext,
type HttpRateLimitDetails,
} from "./schema/index.js"
import { Json } from "./utils/json.js"
import { isRecord } from "./utils/record.js"
import { awsErrorType, providerCodes } from "./utils/provider-codes.js"
const patterns = [
/prompt is too long/i,
@@ -85,43 +84,8 @@ export const isContextOverflowFailure = (failure: unknown) =>
* Whether a failed call may succeed when sent again: rate limits, provider-side failures, transport failures that did
* not deliver an accepted write, and unrecognized failures. Callers decide which calls are safe to repeat.
*/
export const isRetryable = (error: AIError) => {
const override = error.reason.http?.headers["x-should-retry"]
if (override === "true") return true
if (override === "false") return false
switch (error.reason._tag) {
case "RateLimit":
case "ProviderInternal":
return true
// A WebSocket acknowledgment marks delivery accepted before model output may exist.
// Read failures can still recover; the caller chooses retry versus continuation from durable output.
case "Transport":
return (
error.reason.delivery !== "rejected" &&
(error.reason.delivery !== "accepted" || error.reason.operation === "read")
)
case "InvalidProviderOutput":
return error.reason.classification === "incomplete-stream"
// Unrecognized failures retry: classification records affirmative
// deterministic evidence, and transient failures are exactly the ones
// that arrive in shapes no classifier anticipates.
case "UnknownProvider":
return true
case "Authentication":
case "QuotaExceeded":
case "ContentPolicy":
case "InvalidRequest":
case "UnsupportedOperation":
case "Timeout":
return false
default: {
const exhaustive: never = error.reason
return exhaustive
}
}
}
export const isRetryable = (error: AIError) => error.isRetryable
const decodeJson = Schema.decodeUnknownOption(Json)
// OpenCode Zen reports account caps as typed 429/402 errors that are not throttles.
const QUOTA_CODES = new Set([
"insufficient_quota",
@@ -317,40 +281,3 @@ export function classifyProviderFailure(input: ProviderFailure): AIError["reason
if (input.status !== undefined && input.status >= 400 && input.status < 500) return new InvalidRequestError(details)
return new UnknownProviderError(details)
}
function providerCodes(value: unknown) {
const decoded = typeof value === "string" ? Option.getOrUndefined(decodeJson(value)) : value
if (!isRecord(decoded)) return []
const error = isRecord(decoded.error) ? decoded.error : undefined
const inner = error && isRecord(error.innererror) ? error.innererror : undefined
const metadata = error && isRecord(error.metadata) ? error.metadata : undefined
const response = isRecord(decoded.response) ? decoded.response : undefined
const responseError = response && isRecord(response.error) ? response.error : undefined
const exception = isRecord(decoded.exception) ? decoded.exception : undefined
return [
decoded.code,
...awsErrorType(decoded.__type),
...awsErrorType(decoded.code),
decoded.error_type,
error?.code,
error?.type,
error?.status,
error?.error_type,
// Google `google.rpc.ErrorInfo` details carry the specific reason.
...(Array.isArray(error?.details)
? error.details.map((detail) => (isRecord(detail) ? detail.reason : undefined))
: []),
inner?.code,
metadata?.error_type,
responseError?.code,
response?.error_type,
exception?.type,
].filter((value): value is string => typeof value === "string")
}
// AWS restJson1 reports the modeled error in `X-Amzn-Errortype`, `__type` or `code`, possibly
// namespaced (`ns#Name`) or suffixed (`Name:uri`). Keep the shape name only.
// https://smithy.io/2.0/aws/protocols/aws-restjson1-protocol.html#operation-error-serialization
function awsErrorType(value: unknown) {
return typeof value === "string" ? [value.replace(/:.*/s, "").replace(/^[^#]*#/, "")] : []
}
+61
View File
@@ -3,6 +3,7 @@ import { NonNegativeInt } from "@opencode/schema"
import { Tool } from "@opencode/schema/tool"
import { ProviderID, RouteID } from "./ids.js"
import type { LLMResponse } from "./events.js"
import { awsErrorType, providerCodes } from "../utils/provider-codes.js"
export const ProviderFailureClassification = Schema.Literals(["context-overflow", "payload-too-large"])
export type ProviderFailureClassification = typeof ProviderFailureClassification.Type
@@ -167,6 +168,66 @@ export class AIError extends Schema.TaggedError<AIError>()("AI.Error", {
override get message(): string {
return this.reason.message
}
/** HTTP status of the failed response, when the failure came from one. */
get status(): number | undefined {
return this.reason.http?.status
}
/** The provider's error code from the response body or `x-amzn-errortype`, or the transport's system error code. */
get code(): string | undefined {
if (this.reason._tag === "Transport" && this.reason.code !== undefined) return this.reason.code
return [
...(this.reason.body === undefined ? [] : providerCodes(this.reason.body)),
...awsErrorType(this.reason.http?.headers["x-amzn-errortype"]),
][0]
}
/** Delay the provider asked for before retrying, from `retry-after` style headers. */
get retryAfterMs(): number | undefined {
if (this.reason._tag === "RateLimit") return this.reason.retryAfterMs ?? this.reason.rateLimit?.retryAfterMs
if (this.reason._tag === "QuotaExceeded" || this.reason._tag === "ProviderInternal") return this.reason.retryAfterMs
return undefined
}
/**
* Whether a failed call may succeed when sent again: rate limits, provider-side failures, transport failures that did
* not deliver an accepted write, and unrecognized failures. Callers decide which calls are safe to repeat.
*/
get isRetryable(): boolean {
const override = this.reason.http?.headers["x-should-retry"]
if (override === "true") return true
if (override === "false") return false
switch (this.reason._tag) {
case "RateLimit":
case "ProviderInternal":
return true
// A WebSocket acknowledgment marks delivery accepted before model output may exist.
// Read failures can still recover; the caller chooses retry versus continuation from durable output.
case "Transport":
return (
this.reason.delivery !== "rejected" && (this.reason.delivery !== "accepted" || this.reason.operation === "read")
)
case "InvalidProviderOutput":
return this.reason.classification === "incomplete-stream"
// Unrecognized failures retry: classification records affirmative
// deterministic evidence, and transient failures are exactly the ones
// that arrive in shapes no classifier anticipates.
case "UnknownProvider":
return true
case "Authentication":
case "QuotaExceeded":
case "ContentPolicy":
case "InvalidRequest":
case "UnsupportedOperation":
case "Timeout":
return false
default: {
const exhaustive: never = this.reason
return exhaustive
}
}
}
}
/** Return `error` with `partial` attached, or unchanged when there is no partial output. */
+43
View File
@@ -0,0 +1,43 @@
import { Option, Schema } from "effect"
import { Json } from "./json.js"
import { isRecord } from "./record.js"
const decodeJson = Schema.decodeUnknownOption(Json)
/** Error codes a provider error body carries, in their original case. The first is its primary code (`AIError.code`). */
export function providerCodes(value: unknown) {
const decoded = typeof value === "string" ? Option.getOrUndefined(decodeJson(value)) : value
if (!isRecord(decoded)) return []
const error = isRecord(decoded.error) ? decoded.error : undefined
const inner = error && isRecord(error.innererror) ? error.innererror : undefined
const metadata = error && isRecord(error.metadata) ? error.metadata : undefined
const response = isRecord(decoded.response) ? decoded.response : undefined
const responseError = response && isRecord(response.error) ? response.error : undefined
const exception = isRecord(decoded.exception) ? decoded.exception : undefined
return [
decoded.code,
...awsErrorType(decoded.__type),
...awsErrorType(decoded.code),
decoded.error_type,
error?.code,
error?.type,
error?.status,
error?.error_type,
// Google `google.rpc.ErrorInfo` details carry the specific reason.
...(Array.isArray(error?.details)
? error.details.map((detail) => (isRecord(detail) ? detail.reason : undefined))
: []),
inner?.code,
metadata?.error_type,
responseError?.code,
response?.error_type,
exception?.type,
].filter((value): value is string => typeof value === "string")
}
// AWS restJson1 reports the modeled error in `X-Amzn-Errortype`, `__type` or `code`, possibly
// namespaced (`ns#Name`) or suffixed (`Name:uri`). Keep the shape name only.
// https://smithy.io/2.0/aws/protocols/aws-restjson1-protocol.html#operation-error-serialization
export function awsErrorType(value: unknown) {
return typeof value === "string" ? [value.replace(/:.*/s, "").replace(/^[^#]*#/, "")] : []
}
+50 -1
View File
@@ -1,6 +1,6 @@
import { describe, expect, test } from "bun:test"
import { isContextOverflow, isContextOverflowFailure, isRetryable } from "../src/effect.js"
import { AIError, HttpContext } from "../src/schema/index.js"
import { AIError, HttpContext, RateLimitError, TransportError } from "../src/schema/index.js"
import { classifyProviderFailure, providerErrorMessage } from "../src/provider-error.js"
describe("provider error classification", () => {
@@ -716,3 +716,52 @@ describe("provider error messages", () => {
).toEqual([undefined, undefined, undefined, undefined])
})
})
describe("AIError getters", () => {
const rateLimit = new AIError({
reason: new RateLimitError({
message: "Rate limit reached",
http: new HttpContext({ url: "https://api.test/v1", status: 429, headers: { "retry-after": "2" } }),
retryAfterMs: 2000,
}),
})
const invalidBody = '{"error":{"message":"model not found","type":"invalid_request_error","code":"model_not_found"}}'
const invalidRequest = new AIError({
reason: classifyProviderFailure({
message: providerErrorMessage(invalidBody),
status: 404,
rawBody: invalidBody,
http: new HttpContext({ url: "https://api.test/v1", status: 404, headers: {} }),
}),
})
const transport = new AIError({
reason: new TransportError({ message: "socket hang up", transport: "http", operation: "request" }),
})
test("status", () => {
expect([rateLimit.status, invalidRequest.status, transport.status]).toEqual([429, 404, undefined])
})
test("code", () => {
expect([rateLimit.code, invalidRequest.code, transport.code]).toEqual([undefined, "model_not_found", undefined])
expect(
new AIError({
reason: new TransportError({ message: "reset", transport: "http", operation: "read", code: "ECONNRESET" }),
}).code,
).toBe("ECONNRESET")
})
test("isRetryable", () => {
expect(invalidRequest.reason._tag).toBe("InvalidRequest")
expect([rateLimit.isRetryable, invalidRequest.isRetryable, transport.isRetryable]).toEqual([true, false, true])
expect([rateLimit, invalidRequest, transport].map(isRetryable)).toEqual([true, false, true])
})
test("retryAfterMs", () => {
expect([rateLimit.retryAfterMs, invalidRequest.retryAfterMs, transport.retryAfterMs]).toEqual([
2000,
undefined,
undefined,
])
})
})