Error Reference

All errors return a consistent JSON shape:

{
  "error": "QUOTA_EXCEEDED",
  "message": "Monthly action quota exceeded. Upgrade your plan.",
  "request_id": "req-abc-123",
  "retry_after": 0
}

Use error for programmatic handling and request_id for support tickets.

Error Codes

Code	HTTP	Retryable	Resolution
`UNAUTHORIZED`	401	No	Check API key format and validity
`VALIDATION_ERROR`	400	No	Check request body against the schema
`DOMAIN_BLOCKED`	403	No	URL is on the restricted list (banking, streaming, ticketing)
`SESSION_NOT_FOUND`	404	No	Session may have expired — create a new one
`SESSION_BUSY`	409	Yes	Wait for the current request to complete
`SESSION_EXPIRED`	410	No	Session timed out (2min idle or 15min total) — create a new one
`PLAN_RESTRICTED`	402	No	Feature requires a higher plan — upgrade
`NO_SUBSCRIPTION`	402	No	Subscribe to access billing features
`QUOTA_EXCEEDED`	429	No	Monthly action limit reached — upgrade or wait for reset
`RATE_LIMITED`	429	Yes	Too many requests — check `retry_after` field
`PERCEPTION_FAILED`	502	Yes	Page extraction failed — retry the request
`LLM_ERROR`	502	Yes	AI processing failed — retry with backoff
`BROWSER_ERROR`	503	Yes	Browser infrastructure unavailable — retry after 5s
`INTERNAL_ERROR`	500	Yes	Unexpected server error — retry with exponential backoff

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
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:

Plan	Requests/minute
Free	10
Builder	60
Pro	120

When rate limited, the response includes a retry_after field with the number of seconds to wait.

Error Reference

Error Reference

Error Codes

Handling Errors in the SDK

Retry Behavior

Rate Limits

On this page