Skip to main content

​
Error envelope

All errors use the same response envelope as successful responses, with success: false and an error string: 
{
  "success": false,
  "error": "Human-readable error message",
  "meta": {
    "requestId": "uuid-v4",
    "durationMs": 12
  }
}
Always check success before reading data. 
const { success, data, error, meta } = await res.json();

if (!success) {
  console.error(`Request ${meta.requestId} failed: ${error}`);
  // Handle error
} else {
  // Use data
}

​
HTTP status codes

StatusCategoryWhen it occurs
200SuccessRequest completed successfully, credits deducted
400Validation errorInvalid or missing url, bad parameter values
401UnauthorizedNo X-API-Key header provided
403ForbiddenInvalid key, revoked key, expired key, credit limit exceeded, blocklisted URL
422UnresolvableURL hostname could not be resolved (DNS failure)
429Rate limitedGlobal (300/min per IP), per-key RPM, or concurrency limit exceeded
500Server errorPage not accessible, extraction failed, internal error
502Bad gatewayConnection refused to target URL, or SSL certificate invalid
503UnavailableQueue is backed up, service temporarily overloaded
504TimeoutRequest exceeded the 55-second processing limit

​
Error messages

​
Validation errors (400)

MessageCause
"url parameter is required"Missing url query parameter
"Invalid URL"URL fails validation (bad format, private IP, reserved TLD)
"URL exceeds maximum length"URL longer than 2048 characters
"width must be between 320 and 5000"Screenshot width out of range
"height must be between 320 and 5000"Screenshot height out of range
"screenshotColors must be between 2 and 12"Color count out of range

​
Auth errors (401 / 403)

MessageCause
"Missing API key"No X-API-Key header
"Invalid API key"Key not found in the system
"API key has been revoked"Key was manually revoked
"API key has expired"Key passed its expiry date
"Credit limit exceeded"Key exhausted its credit allocation
"URL is blocklisted for this API key"URL is on the key’s blocklist

​
DNS errors (422)

MessageCause
"Could not resolve hostname"URL hostname failed DNS lookup

​
Rate limit errors (429)

MessageCause
"Too many requests"Global IP rate limit (300/min) exceeded
"Rate limit exceeded for this API key"Per-key RPM limit exceeded
"Concurrency limit exceeded for this API key"Too many in-flight requests for this key

​
Gateway errors (502 / 503)

MessageCause
"Connection refused"Target URL actively refused the connection
"SSL certificate error"Target URL has an invalid or expired SSL certificate
"Service temporarily unavailable"Request queue is backed up; retry shortly

​
Server errors (500 / 504)

MessageCause
"Page not accessible"Target URL returned an error or was unreachable
"Extraction failed"Internal error during data extraction
"Request timed out"Processing exceeded 55 seconds

​
Blocked URLs

Certain URLs are automatically blocked to prevent misuse:
  • Private IP ranges — 10.x.x.x, 192.168.x.x, 127.x.x.x, etc.
  • Reserved TLDs — .local, .internal, .localhost, etc.
  • Per-key blocklist — URLs manually added to a key’s blocklist
Requests to blocked URLs return 403 Forbidden with "URL is blocklisted for this API key".

​
Retrying failed requests

StatusShould retry?Strategy
400NoFix the request parameters
401 / 403NoFix authentication or credits
422NoThe hostname doesn’t exist; fix the URL
429YesExponential backoff — see Rate limits
500MaybeRetry once after a short delay; some pages are intermittently unavailable
502MaybeTarget site connection issue; retry once
503YesService overloaded; retry with backoff
504MaybeThe target site may have been slow; retry once