Error Reference

All errors return a consistent JSON shape:

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly action quota exhausted (250/250). Upgrade to Builder for 1,000 actions/month with overage, or start a free 14-day Builder trial: https://webuplink.ai/dashboard?upgrade=true",
  "request_id": "req-abc-123"
}

Use error for programmatic handling and request_id for support tickets — include it when emailing support@webuplink.ai. Retryable errors include a retry_after field (seconds) and a Retry-After header.

Error Codes

Not every 502/503 carries these codes. Our load balancer can emit its own 502/503 responses without a JSON body (for example during a deploy or upstream connection failure). The SDKs map those to INTERNAL_ERROR — check for the JSON error field before branching on a code.

Quota errors carry an upgrade CTA

Hard-stop quota responses on the Free and trial plans (QUOTA_EXCEEDED) and free-tier degradation (FREE_TIER_DEGRADED) include a machine-readable upgrade object, so agents and SDKs can surface the exact next step without parsing prose. Quota errors also include a usage snapshot:

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly action quota exhausted (250/250). Upgrade to Builder for 1,000 actions/month with overage, or start a free 14-day Builder trial: https://webuplink.ai/dashboard?upgrade=true",
  "request_id": "req-abc-123",
  "usage": {
    "actionCount": 250,
    "actionLimit": 250,
    "periodStart": "2026-07-01T00:00:00.000Z"
  },
  "upgrade": {
    "trial": true,
    "plans": ["builder", "pro"],
    "url": "https://webuplink.ai/dashboard?upgrade=true"
  }
}

upgrade.trial is true when the 14-day Builder trial (card required, auto-converts on day 14, cancel anytime) is available from your current plan — i.e. on Free. Trialists get trial: false with a subscribe message instead.

Handling Errors in the SDK

import { WebUplink, WebUplinkError } from 'webuplink';

const client = new WebUplink({
  apiKey: process.env.WEBUPLINK_API_KEY!,
  baseUrl: 'https://api.webuplink.ai',
});

try {
  const page = await client.browse('https://example.com');
} catch (err) {
  if (err instanceof WebUplinkError) {
    console.log(err.code);       // 'QUOTA_EXCEEDED'
    console.log(err.statusCode); // 429
    console.log(err.requestId);  // 'req-abc-123'
    console.log(err.retryable);  // false
    console.log(err.retryAfter); // undefined

    if (err.retryable && err.retryAfter) {
      // Wait and retry
      await new Promise(r => setTimeout(r, err.retryAfter! * 1000));
    }
  }
}

Retry Behavior

The SDK automatically retries retryable errors with the following rules:

• Connection errors (network failures) are always retried with linear backoff
• Server errors with retry_after are retried after the specified wait time
• 429 responses (RATE_LIMITED, QUOTA_EXCEEDED) are never automatically retried, even with retry_after — auto-retrying a throttle amplifies load
• SITE_BLOCKED carries no retry_after, so it is never automatically retried
• Tool execution requests are never automatically retried (non-idempotent)
• Maximum retry attempts: 3 (configurable via maxRetries option)

// Disable retries entirely
const client = new WebUplink({
  apiKey: '...',
  baseUrl: '...',
  retry: false,
});

Rate Limits

Rate limits are per-tenant, per-minute:

Every /v1 response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers. When rate limited, the response includes a retry_after field (and Retry-After header) with the number of seconds to wait.