@zenrows/mcp 2.2.4 → 2.3.0

package/dist/auth/claim-hint.d.ts

@@ -1,3 +1,15 @@
+/**
+ * A per-key credit cap: Fetch, Extract and Browser answer 402 AUTH014, Batch answers
+ * 402 `api_key_cap_reached`. The account still has credits and its other keys still
+ * work, so "buy credits" or "claim your account" would send the user the wrong way.
+ */
+export declare const KEY_CAP_CODES: ReadonlySet<string>;
+export declare const KEY_CAP_NUDGE = "This API key reached one of its credit caps. The account's other API keys still work. Raise or remove the cap at https://app.zenrows.com/settings/api-keys, or wait until it resets (the error detail says when).";
+export declare function isKeyCapError(opts?: {
+    body?: string;
+    code?: string;
+    message?: string;
+}): boolean;
 export declare function isQuotaOrPlanError(opts?: {
     status?: number;
     body?: string;

package/dist/auth/claim-hint.js

@@ -18,6 +18,13 @@ const CLAIM_NUDGE = "Claim your Free account to keep usage and upgrade: ";
  * would otherwise lose the account along with its usage history.
  */
 const SKIP_CODES = new Set(["AUTH006"]);
+/**
+ * A per-key credit cap: Fetch, Extract and Browser answer 402 AUTH014, Batch answers
+ * 402 `api_key_cap_reached`. The account still has credits and its other keys still
+ * work, so "buy credits" or "claim your account" would send the user the wrong way.
+ */
+export const KEY_CAP_CODES = new Set(["AUTH014", "api_key_cap_reached", "BATCH_KEY_CAP_REACHED"]);
+export const KEY_CAP_NUDGE = "This API key reached one of its credit caps. The account's other API keys still work. Raise or remove the cap at https://app.zenrows.com/settings/api-keys, or wait until it resets (the error detail says when).";
 function extractCode(body, code) {
     if (code && typeof code === "string")
         return code;
@@ -35,7 +42,15 @@ function extractCode(body, code) {
         return m?.[1];
     }
 }
+export function isKeyCapError(opts = {}) {
+    const code = extractCode(opts.body, opts.code);
+    if (code && KEY_CAP_CODES.has(code))
+        return true;
+    return /\b(AUTH014|api_key_cap_reached)\b/.test(`${opts.message ?? ""} ${opts.body ?? ""}`);
+}
 export function isQuotaOrPlanError(opts = {}) {
+    if (isKeyCapError(opts))
+        return false;
     const code = extractCode(opts.body, opts.code);
     if (code && SKIP_CODES.has(code))
         return false;
@@ -59,6 +74,9 @@ export function appendClaimHint(text, opts = {}) {
         code: opts.code,
         message: opts.message ?? text,
     };
+    if (isKeyCapError(probe)) {
+        return text.includes(KEY_CAP_NUDGE) ? text : `${text}\n\n${KEY_CAP_NUDGE}`;
+    }
     if (!isQuotaOrPlanError(probe))
         return text;
     const acct = readAccount();

package/dist/batch-api.js

@@ -9,7 +9,7 @@ export function batchBase() {
     const base = env && env.trim() ? env.trim() : DEFAULT_BATCH_API_BASE;
     return base.replace(/\/+$/, "");
 }
-export const TERMINAL_STATUSES = new Set(["completed", "stopped", "deleted"]);
+export const TERMINAL_STATUSES = new Set(["completed", "failed", "stopped", "deleted"]);
 export class BatchError extends Error {
     code;
     status;
@@ -118,6 +118,14 @@ function problemToError(status, body, method, path) {
             detail: cause,
         });
     }
+    if (status === 402 && serverCode === "api_key_cap_reached") {
+        return new BatchError({
+            code: "BATCH_KEY_CAP_REACHED",
+            message: "This API key reached one of its credit caps, so the Batch API refused the request. The account's other API keys still work. Raise or remove the cap at https://app.zenrows.com/settings/api-keys, or wait until it resets (see detail).",
+            status,
+            detail: cause,
+        });
+    }
     if (status === 402) {
         return new BatchError({
             code: "BATCH_QUOTA_EXCEEDED",

package/dist/tools/account.js

@@ -92,7 +92,13 @@ human does not want to wait for the renewal, relay the way to continue now: add
 credit pack at https://app.zenrows.com/billing?topup=open (opens the purchase
 directly) or upgrade at https://app.zenrows.com/plans. Prices are per plan; quote them
 only from this tool's response, never from memory.
-AUTH006 is the concurrency limit, which is a different thing entirely.`,
+AUTH006 is the concurrency limit, which is a different thing entirely.
+
+AUTH014 (Batch: api_key_cap_reached) is different from AUTH004: the account still has
+credits, but this API key hit one of its own credit caps. Other keys keep working. The
+response's api_key.caps lists the calling key's caps: window, credits, used_credits,
+remaining_credits, resets_at, and unavailable (usage could not be read). Relay the
+resets_at time, or raise or remove the cap at https://app.zenrows.com/settings/api-keys.`,
         inputSchema: {},
     }, async () => runAccountUsage(apiKey, opts));
 }

package/dist/tools/batch.js

@@ -215,7 +215,7 @@ Download result_url soon — presigned links expire.`,
     });
     server.registerTool("batch_wait", {
         annotations: { title: "Wait for Batch Job", readOnlyHint: true, destructiveHint: false },
-        description: "Poll batch_status until the job reaches a terminal state (completed, stopped, or deleted).",
+        description: "Poll batch_status until the job reaches a terminal state (completed, failed, stopped, or deleted). A run that hits an API key credit cap ends as failed with failure_reason api_key_cap_reached.",
         inputSchema: {
             job_id: z.string().describe("Batch job id"),
             timeout_ms: z

package/dist/tools/browser-fetch.js

@@ -19,12 +19,28 @@ export async function browserFetch(method, path, apiKey, browserUrl, body, clien
     let data;
     const contentType = response.headers.get("content-type") ?? "";
     const text = await response.text();
-    data = contentType.includes("application/json") && text ? JSON.parse(text) : text;
+    // Errors come back as application/problem+json (e.g. 402 AUTH014), so match any JSON type.
+    data = text;
+    if (text && /[/+]json\b/.test(contentType)) {
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            // keep the raw text
+        }
+    }
     return { ok: response.ok, status: response.status, data };
 }
 export function browserError(result) {
     if (typeof result.data === "object" && result.data !== null && "error" in result.data) {
         return String(result.data.error);
     }
+    if (typeof result.data === "object" && result.data !== null && "code" in result.data) {
+        const d = result.data;
+        return `HTTP ${result.status} (${String(d.code)}): ${String(d.detail ?? d.title ?? "")}`.trim();
+    }
+    if (typeof result.data === "string" && result.data.trim()) {
+        return `HTTP ${result.status}: ${result.data.trim().slice(0, 300)}`;
+    }
     return `HTTP ${result.status}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zenrows/mcp",
-  "version": "2.2.4",
+  "version": "2.3.0",
   "description": "Zenrows MCP server — Fetch, Extract, Batch, and Browser Sessions for AI coding assistants",
   "type": "module",
   "bin": {