Skip to content

armgit / eve

Public Imported from GitHub
0

The Open Framework for Building Agents

Recognize AI Gateway credit and budget refusals (#3322)

e0-gh-vercel-connect[bot]8bb62e2c960a
diff --git a/.changeset/recognize-gateway-budget-refusals.md b/.changeset/recognize-gateway-budget-refusals.md
new file mode 100644
index 000000000..5776ca2ef
--- /dev/null
+++ b/.changeset/recognize-gateway-budget-refusals.md
@@ -0,0 +1,5 @@
+---
+"eve": patch
+---
+
+Recognize AI Gateway credit-balance and project-budget refusals in semantic error summaries.
diff --git a/packages/eve/src/harness/semantic-errors/rules/gateway.ts b/packages/eve/src/harness/semantic-errors/rules/gateway.ts
index 861c45c7c..eb2a2e508 100644
--- a/packages/eve/src/harness/semantic-errors/rules/gateway.ts
+++ b/packages/eve/src/harness/semantic-errors/rules/gateway.ts
@@ -38,6 +38,25 @@ export const GATEWAY_RULES: readonly SemanticErrorRule[] = [
message: (link) => link.message,
hint: "Add a valid credit card or credits in the Vercel dashboard, then retry.",
},
+ {
+ id: "gateway-credit-exhausted",
+ name: "AI Gateway credit balance exhausted",
+ tags: ["gateway", "config", "recoverable"],
+ when: anyOf(
+ typeIs("insufficient_funds"),
+ messageMatches(/A positive credit balance is required/i),
+ ),
+ message: "AI Gateway requires a positive credit balance to process requests.",
+ hint: "Add credits in the Vercel dashboard, then retry.",
+ },
+ {
+ id: "gateway-budget-exhausted",
+ name: "AI Gateway project budget exceeded",
+ tags: ["gateway", "config", "recoverable"],
+ when: anyOf(typeIs("quota_for_entity_exceeded"), messageMatches(/Project budget exceeded/i)),
+ message: "The AI Gateway project budget has been exceeded.",
+ hint: "Ask your administrator to increase the project budget, then retry.",
+ },
{
id: "gateway-free-tier-model-restricted",
name: "Model unavailable on AI Gateway free tier",
diff --git a/packages/eve/src/harness/semantic-errors/semantic-errors.test.ts b/packages/eve/src/harness/semantic-errors/semantic-errors.test.ts
index 9a6da4856..15f133583 100644
--- a/packages/eve/src/harness/semantic-errors/semantic-errors.test.ts
+++ b/packages/eve/src/harness/semantic-errors/semantic-errors.test.ts
@@ -10,6 +10,21 @@ function named(name: string, message: string, extra?: Record<string, unknown>):
return Object.assign(error, extra);
}
+function gatewayUpstreamBillingError(type: string | undefined, message: string): Error {
+ const body = { error: { message, type } };
+ const upstream = Object.assign(new Error("[object Object]"), {
+ data: body,
+ name: "AI_APICallError",
+ responseBody: JSON.stringify(body),
+ statusCode: 402,
+ });
+ return Object.assign(new Error(message, { cause: upstream }), {
+ name: "GatewayInternalServerError",
+ statusCode: 402,
+ type: "internal_server_error",
+ });
+}
+
describe("summarizeKnownError (catalog table)", () => {
const cases: readonly {
readonly title: string;
@@ -24,6 +39,38 @@ describe("summarizeKnownError (catalog table)", () => {
),
id: "gateway-billing-required",
},
+ {
+ title: "gateway credit balance exhausted by upstream type",
+ error: gatewayUpstreamBillingError(
+ "insufficient_funds",
+ "A positive credit balance is required for all requests, including BYOK, so fallback providers remain available.",
+ ),
+ id: "gateway-credit-exhausted",
+ },
+ {
+ title: "gateway project budget exhausted by upstream type",
+ error: gatewayUpstreamBillingError(
+ "quota_for_entity_exceeded",
+ "Project budget exceeded. Current spend: $1.01, limit: $1.00. Please contact your administrator to increase the budget.",
+ ),
+ id: "gateway-budget-exhausted",
+ },
+ {
+ title: "gateway credit balance exhausted by message fallback",
+ error: gatewayUpstreamBillingError(
+ undefined,
+ "A positive credit balance is required for all requests, including BYOK, so fallback providers remain available.",
+ ),
+ id: "gateway-credit-exhausted",
+ },
+ {
+ title: "gateway project budget exhausted by message fallback",
+ error: gatewayUpstreamBillingError(
+ undefined,
+ "Project budget exceeded. Current spend: $1.01, limit: $1.00. Please contact your administrator to increase the budget.",
+ ),
+ id: "gateway-budget-exhausted",
+ },
{
title: "gateway free-tier model restriction",
error: named(
diff --git a/packages/eve/src/harness/semantic-errors/signals.ts b/packages/eve/src/harness/semantic-errors/signals.ts
index ad56f32ea..6e4bf9bd0 100644
--- a/packages/eve/src/harness/semantic-errors/signals.ts
+++ b/packages/eve/src/harness/semantic-errors/signals.ts
@@ -46,9 +46,8 @@ export function extractErrorSignals(error: unknown): ErrorSignals {
if (typeof candidate.statusCode === "number") {
link.statusCode = candidate.statusCode;
}
- if (typeof candidate.type === "string" && candidate.type.length > 0) {
- link.type = candidate.type;
- }
+ const type = readGatewayType(candidate);
+ if (type !== undefined) link.type = type;
if (typeof candidate.hint === "string" && candidate.hint.length > 0) {
link.hint = candidate.hint;
}
@@ -56,3 +55,28 @@ export function extractErrorSignals(error: unknown): ErrorSignals {
}
return { chain };
}
+
+function readGatewayType(candidate: Record<string, unknown>): string | undefined {
+ if (typeof candidate.type === "string" && candidate.type.length > 0) {
+ return candidate.type;
+ }
+
+ const dataType = readGatewayTypeFromBody(candidate.data);
+ if (dataType !== undefined) return dataType;
+
+ if (typeof candidate.responseBody !== "string") return undefined;
+ try {
+ return readGatewayTypeFromBody(JSON.parse(candidate.responseBody));
+ } catch {
+ return undefined;
+ }
+}
+
+function readGatewayTypeFromBody(value: unknown): string | undefined {
+ if (!isObject(value)) return undefined;
+ const nestedError = value.error;
+ if (isObject(nestedError) && typeof nestedError.type === "string") {
+ return nestedError.type.length > 0 ? nestedError.type : undefined;
+ }
+ return typeof value.type === "string" && value.type.length > 0 ? value.type : undefined;
+}