feat: IPNotAllowedError for 403 ip_not_allowed (0.53.0)

CHANGELOG.md

@@ -1,5 +1,9 @@
 # Changelog
 
+## 0.53.0 — 2026-10-05
+
+- **`IPNotAllowedError` for keys restricted to IP addresses.** API keys can now be limited to IP addresses and CIDR ranges in the dashboard; a request from anywhere else answers `403` with `error: "ip_not_allowed"` (not charged). The SDK throws `IPNotAllowedError` with `clientIp` — the address ScrapeBadger saw. It extends `PermissionDeniedError` (and so `AuthenticationError`), so existing handlers still match.
+
 ## 0.52.0 — 2026-10-05
 
 - **`PermissionDeniedError` for keys restricted to specific APIs.** API keys can now be limited to chosen APIs in the dashboard; calling any other API answers `403` with `error: "insufficient_scope"` (and charges nothing). The SDK throws `PermissionDeniedError` for it, with `requiredScope` and `allowedScopes`. It extends `AuthenticationError` — what every non-restriction `403` threw before — so existing `catch` handlers still match.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "scrapebadger",
-  "version": "0.52.0",
+  "version": "0.53.0",
   "description": "Official Node.js SDK for ScrapeBadger - Async web scraping APIs for Twitter, Google, Vinted, Reddit, and more",
   "type": "module",
   "main": "./dist/index.js",

src/index.ts

@@ -50,6 +50,7 @@ export {
   InsufficientCreditsError,
   AccountRestrictedError,
   PermissionDeniedError,
+  IPNotAllowedError,
   ConflictError,
   WebSocketStreamError,
 } from "./internal/exceptions.js";

src/internal/client.ts

@@ -14,6 +14,7 @@ import {
   InsufficientCreditsError,
   AccountRestrictedError,
   PermissionDeniedError,
+  IPNotAllowedError,
   ConflictError,
   ScrapeBadgerError,
 } from "./exceptions.js";
@@ -56,6 +57,7 @@ interface ErrorResponse {
   error?: string;
   required_scope?: string;
   allowed_scopes?: string[];
+  client_ip?: string | null;
 }
 
 /**
@@ -345,6 +347,9 @@ export class BaseClient {
         throw new InsufficientCreditsError(message, errorData.credits_balance);
 
       case 403:
+        if (errorData.error === "ip_not_allowed") {
+          throw new IPNotAllowedError(message, errorData.client_ip ?? null);
+        }
         if (errorData.error === "insufficient_scope") {
           throw new PermissionDeniedError(
             message,

src/internal/exceptions.ts

@@ -50,6 +50,22 @@ export class PermissionDeniedError extends AuthenticationError {
   }
 }
 
+/**
+ * Raised when the API key is restricted to IP addresses and this request came
+ * from another one (HTTP 403, `error: "ip_not_allowed"`). Not charged.
+ */
+export class IPNotAllowedError extends PermissionDeniedError {
+  /** The address ScrapeBadger saw (null when relayed, e.g. via the hosted MCP server) */
+  readonly clientIp: string | null;
+
+  constructor(message = "This API key may not be used from this IP address.", clientIp: string | null = null) {
+    super(message);
+    this.name = "IPNotAllowedError";
+    this.clientIp = clientIp;
+    Object.setPrototypeOf(this, IPNotAllowedError.prototype);
+  }
+}
+
 /**
  * Raised when rate limit is exceeded.
  */

tests/exceptions.test.ts

@@ -206,4 +206,36 @@ describe("Exceptions", () => {
       }
     });
   });
+
+  describe("IPNotAllowedError", () => {
+    it("is thrown on 403 ip_not_allowed with the client IP", async () => {
+      const { BaseClient } = await import("../src/internal/client.js");
+      const { resolveConfig } = await import("../src/internal/config.js");
+      const { IPNotAllowedError, PermissionDeniedError } = await import("../src/internal/exceptions.js");
+      const client = new BaseClient(resolveConfig({ apiKey: "test-key", maxRetries: 0 }));
+      vi.stubGlobal(
+        "fetch",
+        vi.fn().mockResolvedValue(
+          new Response(
+            JSON.stringify({
+              detail: "This request came from 203.0.113.9, which is not on its allowlist.",
+              error: "ip_not_allowed",
+              client_ip: "203.0.113.9",
+            }),
+            { status: 403, headers: { "Content-Type": "application/json" } }
+          )
+        )
+      );
+      try {
+        await client.request("/v1/google/search");
+        expect.fail("Should have thrown IPNotAllowedError");
+      } catch (err) {
+        expect(err).toBeInstanceOf(IPNotAllowedError);
+        expect(err).toBeInstanceOf(PermissionDeniedError);
+        expect((err as InstanceType<typeof IPNotAllowedError>).clientIp).toBe("203.0.113.9");
+      } finally {
+        vi.unstubAllGlobals();
+      }
+    });
+  });
 });