feat: Handle too_many_requests errors / Retry-After header (#187)

Author: davidgrayston-paddle

CHANGELOG.md

@@ -27,6 +27,7 @@ adding additional type guards.
 - Added support for new payment methods `blik`, `mb_way`, `pix` and `upi`. See [related changelog](https://developer.paddle.com/changelog/2025/blik-mbway-payment-methods?utm_source=dx&utm_medium=paddle-node-sdk).
 - Non-catalog discounts on Transactions, see [changelog](https://developer.paddle.com/changelog/2025/custom-discounts?utm_source=dx&utm_medium=paddle-node-sdk)
 - Support `retained_fee` field on totals objects to show the fees retained by Paddle for the adjustment.
+- `ApiError` will now have `retryAfter` property set for [too_many_requests](https://developer.paddle.com/errors/shared/too_many_requests) errors
 
 ### Changed
 

README.md

@@ -2091,7 +2091,7 @@ console.log('Archived Business:', archivedBusiness)
 
 ### Error Handling
 
-If a request fails, Paddle returns an `error` object that contains the same information as [errors returned by the API](https://developer.paddle.com/api-reference/about/errors?utm_source=dx&utm_medium=paddle-node-sdk). You can use the `code` attribute to search an error in [the error reference](https://developer.paddle.com/errors/overview?utm_source=dx&utm_medium=paddle-node-sdk) and to handle the error in your app. Validation errors also return an array of `errors` that tell you which fields failed validation.
+If a request fails, Paddle returns an `error` object that contains the same information as [errors returned by the API](https://developer.paddle.com/api-reference/about/errors?utm_source=dx&utm_medium=paddle-node-sdk). You can use the `code` attribute to search an error in [the error reference](https://developer.paddle.com/errors/overview?utm_source=dx&utm_medium=paddle-node-sdk) and to handle the error in your app. Validation errors also return an array of `errors` that tell you which fields failed validation. The `retryAfter` property will be set for `too_many_requests` errors.
 
 This example shows how to handle an error with the code `conflict`:
 

src/__tests__/internal/base-resource.test.ts

@@ -0,0 +1,110 @@
+import { NodeRuntime } from '../../index.esm.node.js';
+import { Client } from '../../internal/api/client.js';
+import { Environment, ErrorResponse, Response } from '../../internal/index.js';
+import { BaseResource } from '../../internal/base/base-resource.js';
+import { ApiError } from '../../internal/errors/generic.js';
+
+class TestResource extends BaseResource {
+  public async trigger(url: string) {
+    const response = await this.client.get<undefined, Response<object> | ErrorResponse>(url);
+    return this.handleResponse(response);
+  }
+}
+
+const mockFetch = jest.fn();
+
+describe('BaseResource', () => {
+  let client: Client;
+  let resource: TestResource;
+
+  beforeAll(() => {
+    // Mock fetch globally
+    global.fetch = mockFetch;
+  });
+
+  beforeEach(() => {
+    NodeRuntime.initialize();
+    client = new Client('TEST_API_KEY', { environment: Environment.sandbox });
+    resource = new TestResource(client);
+    mockFetch.mockClear();
+  });
+
+  test('throws ApiError with retryAfter when Retry-After header present', async () => {
+    const mockResponse = {
+      status: 429,
+      headers: new Map([['Retry-After', '42']]),
+      json: jest.fn().mockResolvedValue({
+        error: {
+          type: 'request_error',
+          code: 'too_many_requests',
+          detail:
+            'IP address exceeded the allowed rate limit. Retry after the number of seconds in the Retry-After header.',
+          documentation_url: 'https://developer.paddle.com/errors/shared/too_many_requests',
+        },
+        meta: { request_id: 'req_1' },
+      }),
+    };
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    await expect(resource.trigger('/test')).rejects.toBeInstanceOf(ApiError);
+
+    try {
+      await resource.trigger('/test');
+    } catch (err) {
+      const e = err as ApiError;
+      expect(e.type).toBe('request_error');
+      expect(e.code).toBe('too_many_requests');
+      expect(e.detail).toBe(
+        'IP address exceeded the allowed rate limit. Retry after the number of seconds in the Retry-After header.',
+      );
+      expect(e.retryAfter).toBe(42);
+    }
+  });
+
+  test('throws ApiError with undefined retryAfter when header absent', async () => {
+    const mockResponse = {
+      status: 409,
+      headers: new Map(),
+      json: jest.fn().mockResolvedValue({
+        error: {
+          type: 'request_error',
+          code: 'conflict',
+          detail: 'Request conflicts with another change.',
+          documentation_url: 'https://developer.paddle.com/errors/shared/too_many_requests',
+        },
+        meta: { request_id: 'req_2' },
+      }),
+    };
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    await expect(resource.trigger('/test')).rejects.toBeInstanceOf(ApiError);
+
+    try {
+      await resource.trigger('/test');
+    } catch (err) {
+      const e = err as ApiError;
+      expect(e.type).toBe('request_error');
+      expect(e.code).toBe('conflict');
+      expect(e.detail).toBe('Request conflicts with another change.');
+      expect(e.retryAfter).toBeNull();
+    }
+  });
+
+  test('successful responses pass through handleResponse', async () => {
+    const mockResponse = {
+      status: 200,
+      headers: new Map([['Retry-After', '99']]),
+      json: jest.fn().mockResolvedValue({
+        data: { id: 'ok' },
+        meta: { request_id: 'req_ok' },
+      }),
+    };
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const result = await resource.trigger('/ok');
+    expect(result).toEqual({ id: 'ok' });
+  });
+});

src/__tests__/internal/client.test.ts

@@ -0,0 +1,106 @@
+import { NodeRuntime } from '../../index.esm.node.js';
+import { Client } from '../../internal/api/client.js';
+import { Environment } from '../../internal/index.js';
+import { rawResponse } from '../../internal/types/response.js';
+
+const mockFetch = jest.fn();
+
+describe('Client', () => {
+  let client: Client;
+
+  beforeAll(() => {
+    // Mock fetch globally
+    global.fetch = mockFetch;
+  });
+
+  beforeEach(() => {
+    NodeRuntime.initialize();
+
+    client = new Client('TEST_API_KEY', { environment: Environment.sandbox });
+    mockFetch.mockClear();
+  });
+
+  test('should include raw response in GET request', async () => {
+    const mockResponse = {
+      status: 200,
+      headers: new Map([['Retry-After', '60']]),
+      json: jest.fn().mockResolvedValue({
+        data: { id: 'test_id' },
+        meta: { request_id: 'req_123' },
+      }),
+    };
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const result = await client.get('/test-endpoint');
+
+    expect(result).toEqual({
+      data: { id: 'test_id' },
+      meta: { request_id: 'req_123' },
+      [rawResponse]: mockResponse,
+    });
+  });
+
+  test('should include raw response in POST request', async () => {
+    const mockResponse = {
+      status: 200,
+      headers: new Map([['Retry-After', '60']]),
+      json: jest.fn().mockResolvedValue({
+        data: { id: 'test_id' },
+        meta: { request_id: 'req_123' },
+      }),
+    };
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const result = await client.post('/test-endpoint', { test: 'data' });
+
+    expect(result).toEqual({
+      data: { id: 'test_id' },
+      meta: { request_id: 'req_123' },
+      [rawResponse]: mockResponse,
+    });
+  });
+
+  test('should include raw response in PATCH request', async () => {
+    const mockResponse = {
+      status: 200,
+      headers: new Map([['Retry-After', '60']]),
+      json: jest.fn().mockResolvedValue({
+        data: { id: 'test_id' },
+        meta: { request_id: 'req_123' },
+      }),
+    };
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const result = await client.patch('/test-endpoint', { test: 'data' });
+
+    expect(result).toEqual({
+      data: { id: 'test_id' },
+      meta: { request_id: 'req_123' },
+      [rawResponse]: mockResponse,
+    });
+  });
+
+  test('should include raw response in DELETE request', async () => {
+    const mockResponse = {
+      status: 204,
+      headers: new Map([['Retry-After', '60']]),
+      json: jest.fn().mockResolvedValue({
+        data: { id: 'test_id' },
+        meta: { request_id: 'req_123' },
+      }),
+    };
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const result = await client.delete('/test-endpoint');
+
+    expect(result).toEqual({
+      data: { id: 'test_id' },
+      meta: { request_id: 'req_123' },
+      [rawResponse]: mockResponse,
+    });
+  });
+});

src/__tests__/internal/collection.test.ts

@@ -0,0 +1,119 @@
+import { NodeRuntime } from '../../index.esm.node.js';
+import { Client } from '../../internal/api/client.js';
+import { Environment } from '../../internal/index.js';
+import { Collection } from '../../internal/base/collection.js';
+import { ApiError } from '../../internal/errors/generic.js';
+
+class TestCollection extends Collection<Record<string, unknown>, Record<string, unknown>> {
+  fromJson(data: Record<string, unknown>): Record<string, unknown> {
+    return data;
+  }
+}
+
+const mockFetch = jest.fn();
+
+describe('Collection', () => {
+  let client: Client;
+
+  beforeAll(() => {
+    // Mock fetch globally
+    global.fetch = mockFetch;
+  });
+
+  beforeEach(() => {
+    NodeRuntime.initialize();
+    client = new Client('TEST_API_KEY', { environment: Environment.sandbox });
+    mockFetch.mockClear();
+  });
+
+  test('throws ApiError with retryAfter when Retry-After header present (paginated)', async () => {
+    const mockResponse = {
+      status: 429,
+      headers: new Map([['Retry-After', '17']]),
+      json: jest.fn().mockResolvedValue({
+        error: {
+          type: 'request_error',
+          code: 'too_many_requests',
+          detail:
+            'IP address exceeded the allowed rate limit. Retry after the number of seconds in the Retry-After header.',
+          documentation_url: 'https://developer.paddle.com/errors/shared/too_many_requests',
+        },
+        meta: { request_id: 'req_pag_err_1' },
+      }),
+    } as unknown as Response;
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const col = new TestCollection(client, '/paginated');
+
+    await expect(col.next()).rejects.toBeInstanceOf(ApiError);
+
+    try {
+      await col.next();
+    } catch (err) {
+      const e = err as ApiError;
+      expect(e.type).toBe('request_error');
+      expect(e.code).toBe('too_many_requests');
+      expect(e.retryAfter).toBe(17);
+    }
+  });
+
+  test('throws ApiError with undefined retryAfter when header absent (paginated)', async () => {
+    const mockResponse = {
+      status: 429,
+      headers: new Map(),
+      json: jest.fn().mockResolvedValue({
+        error: {
+          type: 'request_error',
+          code: 'conflict',
+          detail: 'Request conflicts with another change.',
+          documentation_url: 'https://developer.paddle.com/errors/shared/too_many_requests',
+        },
+        meta: { request_id: 'req_pag_err_2' },
+      }),
+    } as unknown as Response;
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const col = new TestCollection(client, '/paginated');
+
+    await expect(col.next()).rejects.toBeInstanceOf(ApiError);
+
+    try {
+      await col.next();
+    } catch (err) {
+      const e = err as ApiError;
+      expect(e.type).toBe('request_error');
+      expect(e.code).toBe('conflict');
+      expect(e.retryAfter).toBeNull();
+    }
+  });
+
+  test('successful paginated response maps data and updates pagination', async () => {
+    const mockResponse = {
+      status: 200,
+      headers: new Map(),
+      json: jest.fn().mockResolvedValue({
+        data: [{ id: 'a' }, { id: 'b' }],
+        meta: {
+          request_id: 'req_pag_ok',
+          pagination: {
+            per_page: 2,
+            next: '/paginated?page=2',
+            has_more: true,
+            estimated_total: 4,
+          },
+        },
+      }),
+    } as unknown as Response;
+
+    mockFetch.mockResolvedValue(mockResponse);
+
+    const col = new TestCollection(client, '/paginated');
+    const result = await col.next();
+
+    expect(result).toEqual([{ id: 'a' }, { id: 'b' }]);
+    expect(col.hasMore).toBe(true);
+    expect(col.estimatedTotal).toBe(4);
+  });
+});