feat: add .type field to APIError for error kind identification (#790)

Expose `error.error.type` (e.g. `"rate_limit_error"`,
`"overloaded_error"`) as a top-level `.type` field on `APIError`. This
lets users identify error kinds uniformly across HTTP errors and
streaming errors, since streaming errors arrive as SSE error events with
HTTP 200 status (making `instanceof` and status code checks unreliable).

Equivalent of
stainless-sdks/anthropic-python#1587 for
TypeScript.

```typescript
try {
  for await (const event of stream) { /* ... */ }
} catch (err) {
  if (err instanceof Anthropic.APIError) {
    if (err.type === 'rate_limit_error' || err.type === 'overloaded_error') {
      // retry after backoff — works for both streaming and non-streaming
    }
  }
}
```

Author: renfredxh

src/core/error.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { castToError } from '../internal/errors';
+import type { ErrorType } from '../resources/shared';
 
 export class AnthropicError extends Error {}
 
@@ -18,12 +19,22 @@ export class APIError<
 
   readonly requestID: string | null | undefined;
 
-  constructor(status: TStatus, error: TError, message: string | undefined, headers: THeaders) {
+  /** The `error.type` from the API response body, e.g. `"rate_limit_error"` */
+  readonly type: ErrorType | null;
+
+  constructor(
+    status: TStatus,
+    error: TError,
+    message: string | undefined,
+    headers: THeaders,
+    type?: ErrorType | null,
+  ) {
     super(`${APIError.makeMessage(status, error, message)}`);
     this.status = status;
     this.headers = headers;
     this.requestID = headers?.get('request-id');
     this.error = error;
+    this.type = type ?? null;
   }
 
   private static makeMessage(status: number | undefined, error: any, message: string | undefined) {
@@ -58,40 +69,41 @@ export class APIError<
     }
 
     const error = errorResponse as Record<string, any>;
+    const type = error?.['error']?.['type'] as ErrorType | undefined;
 
     if (status === 400) {
-      return new BadRequestError(status, error, message, headers);
+      return new BadRequestError(status, error, message, headers, type);
     }
 
     if (status === 401) {
-      return new AuthenticationError(status, error, message, headers);
+      return new AuthenticationError(status, error, message, headers, type);
     }
 
     if (status === 403) {
-      return new PermissionDeniedError(status, error, message, headers);
+      return new PermissionDeniedError(status, error, message, headers, type);
     }
 
     if (status === 404) {
-      return new NotFoundError(status, error, message, headers);
+      return new NotFoundError(status, error, message, headers, type);
     }
 
     if (status === 409) {
-      return new ConflictError(status, error, message, headers);
+      return new ConflictError(status, error, message, headers, type);
     }
 
     if (status === 422) {
-      return new UnprocessableEntityError(status, error, message, headers);
+      return new UnprocessableEntityError(status, error, message, headers, type);
     }
 
     if (status === 429) {
-      return new RateLimitError(status, error, message, headers);
+      return new RateLimitError(status, error, message, headers, type);
     }
 
     if (status >= 500) {
-      return new InternalServerError(status, error, message, headers);
+      return new InternalServerError(status, error, message, headers, type);
     }
 
-    return new APIError(status, error, message, headers);
+    return new APIError(status, error, message, headers, type);
   }
 }
 

src/core/streaming.ts

@@ -10,6 +10,7 @@ import { loggerFor } from '../internal/utils/log';
 import type { BaseAnthropic } from '../client';
 
 import { APIError } from './error';
+import type { ErrorType } from '../resources/shared';
 
 type Bytes = string | ArrayBuffer | Uint8Array | null | undefined;
 
@@ -80,7 +81,9 @@ export class Stream<Item> implements AsyncIterable<Item> {
           }
 
           if (sse.event === 'error') {
-            throw new APIError(undefined, safeJSON(sse.data) ?? sse.data, undefined, response.headers);
+            const body = safeJSON(sse.data) ?? sse.data;
+            const type = body?.error?.type as ErrorType | undefined;
+            throw new APIError(undefined, body, undefined, response.headers, type);
           }
         }
         done = true;

tests/index.test.ts

@@ -1,6 +1,7 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 
 import { APIPromise } from '@anthropic-ai/sdk/core/api-promise';
+import { APIError } from '@anthropic-ai/sdk/core/error';
 
 import util from 'node:util';
 import Anthropic from '@anthropic-ai/sdk';
@@ -772,4 +773,35 @@ describe('retries', () => {
     ).toEqual(JSON.stringify({ a: 1 }));
     expect(count).toEqual(3);
   });
+
+  test('HTTP error response exposes error type', async () => {
+    const client = new Anthropic({
+      apiKey: 'test-key',
+      fetch: () =>
+        Promise.resolve(
+          new Response(
+            JSON.stringify({
+              type: 'error',
+              error: { type: 'invalid_request_error', message: 'Bad request' },
+            }),
+            { status: 400, headers: { 'Content-Type': 'application/json' } },
+          ),
+        ),
+    });
+
+    try {
+      await client.messages.create({
+        model: 'claude-sonnet-4-5-20250929',
+        max_tokens: 1,
+        messages: [{ role: 'user', content: 'hi' }],
+      });
+      throw new Error('Expected request to throw');
+    } catch (err) {
+      expect(err).toBeInstanceOf(APIError);
+      if (err instanceof APIError) {
+        expect(err.type).toBe('invalid_request_error');
+        expect(err.status).toBe(400);
+      }
+    }
+  });
 });

tests/streaming.test.ts

@@ -243,3 +243,43 @@ test('error handling', async () => {
   );
   await err.toBeInstanceOf(APIError);
 });
+
+test('APIError.generate() exposes error type', () => {
+  const error = APIError.generate(
+    400,
+    { type: 'error', error: { type: 'invalid_request_error', message: 'Bad request' } },
+    undefined,
+    new Headers({ 'request-id': 'req_123' }),
+  );
+  expect(error.type).toBe('invalid_request_error');
+  expect(error.status).toBe(400);
+});
+
+test('APIError.generate() sets type to null when absent', () => {
+  const error = APIError.generate(500, { message: 'Internal error' }, undefined, new Headers());
+  expect(error.type).toBeNull();
+});
+
+test('error event exposes error type', async () => {
+  async function* body(): AsyncGenerator<Buffer> {
+    yield Buffer.from('event: error\n');
+    yield Buffer.from('data: {"type":"error","error":{"type":"overloaded_error","message":"Overloaded"}}');
+    yield Buffer.from('\n\n');
+  }
+
+  const stream = Stream.fromSSEResponse(
+    new Response(await ReadableStreamFrom(body())),
+    new AbortController(),
+  );
+
+  try {
+    for await (const _event of stream) {
+    }
+    throw new Error('Expected stream to throw');
+  } catch (err) {
+    expect(err).toBeInstanceOf(APIError);
+    if (err instanceof APIError) {
+      expect(err.type).toBe('overloaded_error');
+    }
+  }
+});