feat: add TemporarilyUnavailableError for 503 responses

Author: boutetnico

src/client.ts

@@ -5,6 +5,7 @@ import {
   SubscriptionRequiredError,
   NotFoundError,
   RateLimitError,
+  TemporarilyUnavailableError,
   UpstreamError,
 } from "./errors.js";
 import type {
@@ -101,6 +102,11 @@ export class RdapClient {
       throw new RateLimitError(message, error, retryAfter ? parseInt(retryAfter, 10) : null);
     }
 
+    if (response.status === 503) {
+      const retryAfter = response.headers.get("Retry-After");
+      throw new TemporarilyUnavailableError(message, error, retryAfter ? parseInt(retryAfter, 10) : null);
+    }
+
     const ErrorClass = ERROR_MAP[response.status];
     if (ErrorClass) {
       throw new ErrorClass(message, error);

src/errors.ts

@@ -55,6 +55,17 @@ export class RateLimitError extends RdapApiError {
   }
 }
 
+/** Raised when the domain data is temporarily unavailable (HTTP 503). */
+export class TemporarilyUnavailableError extends RdapApiError {
+  readonly retryAfter: number | null;
+
+  constructor(message: string, error: string, retryAfter: number | null) {
+    super(message, 503, error);
+    this.name = "TemporarilyUnavailableError";
+    this.retryAfter = retryAfter;
+  }
+}
+
 /** Raised when the upstream RDAP server fails (HTTP 502). */
 export class UpstreamError extends RdapApiError {
   constructor(message: string, error: string) {

src/index.ts

@@ -6,6 +6,7 @@ export {
   NotFoundError,
   RateLimitError,
   SubscriptionRequiredError,
+  TemporarilyUnavailableError,
   UpstreamError,
   ValidationError,
 } from "./errors.js";

tests/client.test.ts

@@ -4,6 +4,7 @@ import {
   AuthenticationError,
   NotFoundError,
   RateLimitError,
+  TemporarilyUnavailableError,
   RdapApiError,
   SubscriptionRequiredError,
   UpstreamError,
@@ -334,6 +335,40 @@ describe("error handling", () => {
     }
   });
 
+  it("throws TemporarilyUnavailableError on 503 with retryAfter", async () => {
+    const client = new RdapClient("test-key", { baseUrl: BASE_URL });
+    globalThis.fetch = mockFetch(
+      { error: "temporarily_unavailable", message: "Data for this domain is temporarily unavailable." },
+      503,
+      { "Retry-After": "300" },
+    );
+
+    try {
+      await client.domain("test.com");
+      expect.fail("Should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(TemporarilyUnavailableError);
+      expect((err as TemporarilyUnavailableError).retryAfter).toBe(300);
+      expect((err as TemporarilyUnavailableError).statusCode).toBe(503);
+    }
+  });
+
+  it("throws TemporarilyUnavailableError with null retryAfter when header missing", async () => {
+    const client = new RdapClient("test-key", { baseUrl: BASE_URL });
+    globalThis.fetch = mockFetch(
+      { error: "temporarily_unavailable", message: "Data for this domain is temporarily unavailable." },
+      503,
+    );
+
+    try {
+      await client.domain("test.com");
+      expect.fail("Should have thrown");
+    } catch (err) {
+      expect(err).toBeInstanceOf(TemporarilyUnavailableError);
+      expect((err as TemporarilyUnavailableError).retryAfter).toBeNull();
+    }
+  });
+
   it("throws UpstreamError on 502", async () => {
     const client = new RdapClient("test-key", { baseUrl: BASE_URL });
     globalThis.fetch = mockFetch(

tests/errors.test.ts

@@ -6,6 +6,7 @@ import {
   SubscriptionRequiredError,
   NotFoundError,
   RateLimitError,
+  TemporarilyUnavailableError,
   UpstreamError,
 } from "../src/errors.js";
 
@@ -82,6 +83,22 @@ describe("RateLimitError", () => {
   });
 });
 
+describe("TemporarilyUnavailableError", () => {
+  it("has status 503, retryAfter, and correct prototype chain", () => {
+    const err = new TemporarilyUnavailableError("Temporarily unavailable", "temporarily_unavailable", 300);
+    expect(err.statusCode).toBe(503);
+    expect(err.retryAfter).toBe(300);
+    expect(err.name).toBe("TemporarilyUnavailableError");
+    expect(err).toBeInstanceOf(TemporarilyUnavailableError);
+    expect(err).toBeInstanceOf(RdapApiError);
+  });
+
+  it("handles null retryAfter", () => {
+    const err = new TemporarilyUnavailableError("Temporarily unavailable", "temporarily_unavailable", null);
+    expect(err.retryAfter).toBeNull();
+  });
+});
+
 describe("UpstreamError", () => {
   it("has status 502 and correct prototype chain", () => {
     const err = new UpstreamError("Upstream failed", "upstream_error");