Add explicit handling for rate-limit errors

src/common/exceptions/bad-request.exception.ts

@@ -1,6 +1,8 @@
-export class BadRequestException extends Error {
-  readonly status: number = 400;
-  readonly name: string = 'BadRequestException';
+import { RequestException } from '../interfaces/request-exception.interface';
+
+export class BadRequestException extends Error implements RequestException {
+  readonly status = 400;
+  readonly name = 'BadRequestException';
   readonly message: string = 'Bad request';
   readonly code?: string;
   readonly errors?: unknown[];

src/common/exceptions/generic-server.exception.ts

@@ -1,5 +1,7 @@
-export class GenericServerException extends Error {
-  readonly name: string = 'GenericServerException';
+import { RequestException } from '../interfaces/request-exception.interface';
+
+export class GenericServerException extends Error implements RequestException {
+  readonly name = 'GenericServerException';
   readonly message: string = 'The request could not be completed.';
 
   constructor(

src/common/exceptions/index.ts

@@ -3,6 +3,7 @@ export * from './bad-request.exception';
 export * from './no-api-key-provided.exception';
 export * from './not-found.exception';
 export * from './oauth.exception';
+export * from './rate-limit-exceeded.exception';
 export * from './signature-verification.exception';
 export * from './unauthorized.exception';
 export * from './unprocessable-entity.exception';

src/common/exceptions/no-api-key-provided.exception.ts

@@ -1,7 +1,7 @@
 export class NoApiKeyProvidedException extends Error {
-  readonly status: number = 500;
-  readonly name: string = 'NoApiKeyProvidedException';
-  readonly message: string =
+  readonly status = 500;
+  readonly name = 'NoApiKeyProvidedException';
+  readonly message =
     `Missing API key. Pass it to the constructor (new WorkOS("sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU")) ` +
     `or define it in the WORKOS_API_KEY environment variable.`;
 }

src/common/exceptions/not-found.exception.ts

@@ -1,6 +1,8 @@
-export class NotFoundException extends Error {
-  readonly status: number = 404;
-  readonly name: string = 'NotFoundException';
+import { RequestException } from '../interfaces/request-exception.interface';
+
+export class NotFoundException extends Error implements RequestException {
+  readonly status = 404;
+  readonly name = 'NotFoundException';
   readonly message: string;
   readonly code?: string;
   readonly requestID: string;

src/common/exceptions/oauth.exception.ts

@@ -1,5 +1,7 @@
-export class OauthException extends Error {
-  readonly name: string = 'OauthException';
+import { RequestException } from '../interfaces/request-exception.interface';
+
+export class OauthException extends Error implements RequestException {
+  readonly name = 'OauthException';
 
   constructor(
     readonly status: number,

src/common/exceptions/rate-limit-exceeded.exception.ts

@@ -0,0 +1,20 @@
+import { RequestException } from '../interfaces/request-exception.interface';
+
+export class RateLimitExceededException
+  extends Error
+  implements RequestException
+{
+  readonly name = 'RateLimitExceededException';
+  readonly status = 429;
+
+  constructor(
+    readonly message: string,
+    readonly requestID: string,
+    /**
+     * The number of seconds to wait before retrying the request.
+     */
+    readonly retryAfter: number | null,
+  ) {
+    super();
+  }
+}

src/common/exceptions/signature-verification.exception.ts

@@ -1,5 +1,5 @@
 export class SignatureVerificationException extends Error {
-  readonly name: string = 'SignatureVerificationException';
+  readonly name = 'SignatureVerificationException';
 
   constructor(message: string) {
     super(message || 'Signature verification failed.');

src/common/exceptions/unauthorized.exception.ts

@@ -1,6 +1,8 @@
-export class UnauthorizedException extends Error {
-  readonly status: number = 401;
-  readonly name: string = 'UnauthorizedException';
+import { RequestException } from '../interfaces/request-exception.interface';
+
+export class UnauthorizedException extends Error implements RequestException {
+  readonly status = 401;
+  readonly name = 'UnauthorizedException';
   readonly message: string;
 
   constructor(readonly requestID: string) {

src/common/exceptions/unprocessable-entity.exception.ts

@@ -1,10 +1,14 @@
 import pluralize from 'pluralize';
 
 import { UnprocessableEntityError } from '../interfaces';
-
-export class UnprocessableEntityException extends Error {
-  readonly status: number = 422;
-  readonly name: string = 'UnprocessableEntityException';
+import { RequestException } from '../interfaces/request-exception.interface';
+
+export class UnprocessableEntityException
+  extends Error
+  implements RequestException
+{
+  readonly status = 422;
+  readonly name = 'UnprocessableEntityException';
   readonly message: string = 'Unprocessable entity';
   readonly code?: string;
   readonly requestID: string;

src/common/interfaces/request-exception.interface.ts

@@ -0,0 +1,5 @@
+export interface RequestException {
+  readonly status: number;
+  readonly message: string;
+  readonly requestID: string;
+}

src/workos.spec.ts

@@ -8,6 +8,7 @@ import {
   OauthException,
 } from './common/exceptions';
 import { WorkOS } from './workos';
+import { RateLimitExceededException } from './common/exceptions/rate-limit-exceeded.exception';
 
 describe('WorkOS', () => {
   beforeEach(() => fetch.resetMocks());
@@ -198,6 +199,7 @@ describe('WorkOS', () => {
         );
       });
     });
+
     describe('when the api responds with a 400 and an error/error_description', () => {
       it('throws an OauthException', async () => {
         fetchOnce(
@@ -222,6 +224,30 @@ describe('WorkOS', () => {
       });
     });
 
+    describe('when the api responses with a 429', () => {
+      it('throws a RateLimitExceededException', async () => {
+        fetchOnce(
+          {
+            message: 'Too many requests',
+          },
+          {
+            status: 429,
+            headers: { 'X-Request-ID': 'a-request-id', 'Retry-After': '10' },
+          },
+        );
+
+        const workos = new WorkOS('sk_test_Sz3IQjepeSWaI4cMS4ms4sMuU');
+
+        await expect(workos.get('/path')).rejects.toStrictEqual(
+          new RateLimitExceededException(
+            'Too many requests',
+            'a-request-id',
+            10,
+          ),
+        );
+      });
+    });
+
     describe('when the entity is null', () => {
       it('sends a null body', async () => {
         fetchOnce();

src/workos.ts

@@ -5,6 +5,7 @@ import {
   UnauthorizedException,
   UnprocessableEntityException,
   OauthException,
+  RateLimitExceededException,
 } from './common/exceptions';
 import {
   GetOptions,
@@ -214,6 +215,15 @@ export class WorkOS {
             requestID,
           });
         }
+        case 429: {
+          const retryAfter = headers.get('Retry-After');
+
+          throw new RateLimitExceededException(
+            data.message,
+            requestID,
+            retryAfter ? Number(retryAfter) : null,
+          );
+        }
         default: {
           if (error || errorDescription) {
             throw new OauthException(