@ai-sdk/gateway 0.0.0-64aae7dd-20260114144918 → 0.0.0-98261322-20260122142521

package/src/errors/create-gateway-error.ts

@@ -0,0 +1,132 @@
+import { z } from 'zod/v4';
+import type { GatewayError } from './gateway-error';
+import { GatewayAuthenticationError } from './gateway-authentication-error';
+import { GatewayInvalidRequestError } from './gateway-invalid-request-error';
+import { GatewayRateLimitError } from './gateway-rate-limit-error';
+import {
+  GatewayModelNotFoundError,
+  modelNotFoundParamSchema,
+} from './gateway-model-not-found-error';
+import { GatewayInternalServerError } from './gateway-internal-server-error';
+import { GatewayResponseError } from './gateway-response-error';
+import {
+  InferSchema,
+  lazySchema,
+  safeValidateTypes,
+  validateTypes,
+  zodSchema,
+} from '@ai-sdk/provider-utils';
+
+export async function createGatewayErrorFromResponse({
+  response,
+  statusCode,
+  defaultMessage = 'Gateway request failed',
+  cause,
+  authMethod,
+}: {
+  response: unknown;
+  statusCode: number;
+  defaultMessage?: string;
+  cause?: unknown;
+  authMethod?: 'api-key' | 'oidc';
+}): Promise<GatewayError> {
+  const parseResult = await safeValidateTypes({
+    value: response,
+    schema: gatewayErrorResponseSchema,
+  });
+
+  if (!parseResult.success) {
+    // Try to extract generationId even if validation failed
+    const rawGenerationId =
+      typeof response === 'object' &&
+      response !== null &&
+      'generationId' in response
+        ? (response as { generationId?: string }).generationId
+        : undefined;
+
+    return new GatewayResponseError({
+      message: `Invalid error response format: ${defaultMessage}`,
+      statusCode,
+      response,
+      validationError: parseResult.error,
+      cause,
+      generationId: rawGenerationId,
+    });
+  }
+
+  const validatedResponse: GatewayErrorResponse = parseResult.value;
+  const errorType = validatedResponse.error.type;
+  const message = validatedResponse.error.message;
+  const generationId = validatedResponse.generationId ?? undefined;
+
+  switch (errorType) {
+    case 'authentication_error':
+      return GatewayAuthenticationError.createContextualError({
+        apiKeyProvided: authMethod === 'api-key',
+        oidcTokenProvided: authMethod === 'oidc',
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'invalid_request_error':
+      return new GatewayInvalidRequestError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'rate_limit_exceeded':
+      return new GatewayRateLimitError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    case 'model_not_found': {
+      const modelResult = await safeValidateTypes({
+        value: validatedResponse.error.param,
+        schema: modelNotFoundParamSchema,
+      });
+
+      return new GatewayModelNotFoundError({
+        message,
+        statusCode,
+        modelId: modelResult.success ? modelResult.value.modelId : undefined,
+        cause,
+        generationId,
+      });
+    }
+    case 'internal_server_error':
+      return new GatewayInternalServerError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+    default:
+      return new GatewayInternalServerError({
+        message,
+        statusCode,
+        cause,
+        generationId,
+      });
+  }
+}
+
+const gatewayErrorResponseSchema = lazySchema(() =>
+  zodSchema(
+    z.object({
+      error: z.object({
+        message: z.string(),
+        type: z.string().nullish(),
+        param: z.unknown().nullish(),
+        code: z.union([z.string(), z.number()]).nullish(),
+      }),
+      generationId: z.string().nullish(),
+    }),
+  ),
+);
+
+export type GatewayErrorResponse = InferSchema<
+  typeof gatewayErrorResponseSchema
+>;

package/src/errors/extract-api-call-response.test.ts

@@ -0,0 +1,270 @@
+import { describe, expect, it } from 'vitest';
+import { APICallError } from '@ai-sdk/provider';
+import { extractApiCallResponse } from './extract-api-call-response';
+
+describe('extractResponseFromAPICallError', () => {
+  describe('when error.data is available', () => {
+    it('should return error.data when successfully parsed by AI SDK', () => {
+      const parsedData = {
+        error: { message: 'Parsed error', type: 'authentication_error' },
+      };
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 401,
+        data: parsedData,
+        responseHeaders: {},
+        responseBody: JSON.stringify({ different: 'data' }),
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe(parsedData); // Should prefer parsed data over responseBody
+    });
+
+    it('should return error.data even when it is null', () => {
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: null,
+        responseHeaders: {},
+        responseBody: '{"fallback": "data"}',
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBeNull(); // Should return null, not fallback to responseBody
+    });
+
+    it('should return error.data even when it is an empty object', () => {
+      const emptyData = {};
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 400,
+        data: emptyData,
+        responseHeaders: {},
+        responseBody: '{"fallback": "data"}',
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe(emptyData); // Should return empty object, not fallback
+    });
+  });
+
+  describe('when error.data is undefined', () => {
+    it('should parse and return responseBody as JSON when valid', () => {
+      const responseData = {
+        ferror: { message: 'Malformed error', type: 'model_not_found' },
+      };
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 404,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: JSON.stringify(responseData),
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toEqual(responseData);
+    });
+
+    it('should return raw responseBody when JSON parsing fails', () => {
+      const invalidJson = 'This is not valid JSON';
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: invalidJson,
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe(invalidJson);
+    });
+
+    it('should handle HTML error responses', () => {
+      const htmlResponse =
+        '<html><body><h1>500 Internal Server Error</h1></body></html>';
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: htmlResponse,
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe(htmlResponse);
+    });
+
+    it('should handle empty string responseBody', () => {
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 502,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: '',
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe('');
+    });
+
+    it('should handle malformed JSON gracefully', () => {
+      const malformedJson = '{"incomplete": json';
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: malformedJson,
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe(malformedJson); // Should return raw string, not throw
+    });
+
+    it('should parse complex nested JSON structures', () => {
+      const complexData = {
+        error: {
+          message: 'Complex error',
+          type: 'validation_error',
+          details: {
+            field: 'prompt',
+            issues: [
+              { code: 'too_long', message: 'Prompt exceeds maximum length' },
+              {
+                code: 'invalid_format',
+                message: 'Contains invalid characters',
+              },
+            ],
+          },
+        },
+        metadata: {
+          requestId: '12345',
+          timestamp: '2024-01-01T00:00:00Z',
+        },
+      };
+
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 400,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: JSON.stringify(complexData),
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toEqual(complexData);
+    });
+  });
+
+  describe('when responseBody is not available', () => {
+    it('should return empty object when both data and responseBody are undefined', () => {
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: undefined as any, // Simulating missing responseBody
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toEqual({});
+    });
+
+    it('should return empty object when responseBody is null', () => {
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: null as any,
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toEqual({});
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle numeric responseBody', () => {
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: '404',
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe(404); // Should parse as number
+    });
+
+    it('should handle boolean responseBody', () => {
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 500,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: 'true',
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toBe(true); // Should parse as boolean
+    });
+
+    it('should handle array responseBody', () => {
+      const arrayData = ['error1', 'error2', 'error3'];
+      const apiCallError = new APICallError({
+        message: 'Request failed',
+        statusCode: 400,
+        data: undefined,
+        responseHeaders: {},
+        responseBody: JSON.stringify(arrayData),
+        url: 'http://test.url',
+        requestBodyValues: {},
+      });
+
+      const result = extractApiCallResponse(apiCallError);
+
+      expect(result).toEqual(arrayData);
+    });
+  });
+});

package/src/errors/extract-api-call-response.ts

@@ -0,0 +1,15 @@
+import type { APICallError } from '@ai-sdk/provider';
+
+export function extractApiCallResponse(error: APICallError): unknown {
+  if (error.data !== undefined) {
+    return error.data;
+  }
+  if (error.responseBody != null) {
+    try {
+      return JSON.parse(error.responseBody);
+    } catch {
+      return error.responseBody;
+    }
+  }
+  return {};
+}

package/src/errors/gateway-authentication-error.ts

@@ -0,0 +1,84 @@
+import { GatewayError } from './gateway-error';
+
+const name = 'GatewayAuthenticationError';
+const marker = `vercel.ai.gateway.error.${name}`;
+const symbol = Symbol.for(marker);
+
+/**
+ * Authentication failed - invalid API key or OIDC token
+ */
+export class GatewayAuthenticationError extends GatewayError {
+  private readonly [symbol] = true; // used in isInstance
+
+  readonly name = name;
+  readonly type = 'authentication_error';
+
+  constructor({
+    message = 'Authentication failed',
+    statusCode = 401,
+    cause,
+    generationId,
+  }: {
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  } = {}) {
+    super({ message, statusCode, cause, generationId });
+  }
+
+  static isInstance(error: unknown): error is GatewayAuthenticationError {
+    return GatewayError.hasMarker(error) && symbol in error;
+  }
+
+  /**
+   * Creates a contextual error message when authentication fails
+   */
+  static createContextualError({
+    apiKeyProvided,
+    oidcTokenProvided,
+    message = 'Authentication failed',
+    statusCode = 401,
+    cause,
+    generationId,
+  }: {
+    apiKeyProvided: boolean;
+    oidcTokenProvided: boolean;
+    message?: string;
+    statusCode?: number;
+    cause?: unknown;
+    generationId?: string;
+  }): GatewayAuthenticationError {
+    let contextualMessage: string;
+
+    if (apiKeyProvided) {
+      contextualMessage = `AI Gateway authentication failed: Invalid API key.
+
+Create a new API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys
+
+Provide via 'apiKey' option or 'AI_GATEWAY_API_KEY' environment variable.`;
+    } else if (oidcTokenProvided) {
+      contextualMessage = `AI Gateway authentication failed: Invalid OIDC token.
+
+Run 'npx vercel link' to link your project, then 'vc env pull' to fetch the token.
+
+Alternatively, use an API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys`;
+    } else {
+      contextualMessage = `AI Gateway authentication failed: No authentication provided.
+
+Option 1 - API key:
+Create an API key: https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai%2Fapi-keys
+Provide via 'apiKey' option or 'AI_GATEWAY_API_KEY' environment variable.
+
+Option 2 - OIDC token:
+Run 'npx vercel link' to link your project, then 'vc env pull' to fetch the token.`;
+    }
+
+    return new GatewayAuthenticationError({
+      message: contextualMessage,
+      statusCode,
+      cause,
+      generationId,
+    });
+  }
+}