Errors

Every failed response has "success": false. What’s under error takes one of two shapes, depending on where the request failed.

Platform-level errors

Failures in authentication, credits, rate limiting, or an unrecognized route come from shared middleware that runs before any tool-specific code, and return a structured object with a stable code you can match on in your own error handling:

{
  "success": false,
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits for this request. Buy a top-up pack or wait for your cycle to renew."
  }
}

error.code

string

A stable, machine-readable identifier. Safe to switch on.

error.message

string

A human-readable explanation. Safe to show a user, not guaranteed to stay word-for-word identical between API versions.

Endpoint-level errors

Validation and execution failures inside an individual tool (a missing url, an unreachable target, a malformed upload) return error as a plain string instead:

{
  "success": false,
  "error": "The `url` query parameter is required"
}

Check the type of error before reading it: typeof error === "object" means a stable code is available; typeof error === "string" means it’s a message meant for a human, not for pattern matching. Both shapes always sit under the same error key.

Status codes

Status	Meaning
`200`	Success (or, for `/broken-links/crawl` and `/link-extract/crawl` status polling, a job that’s still running)
`202`	A crawl job was accepted and queued — response includes a `jobId`
`400`	Bad request — missing or invalid parameters, or a target URL that can’t be processed
`401`	Missing, malformed, or revoked API key
`402`	Signed-in balance doesn’t cover this request’s credit cost
`404`	Unknown `/v1` route, or a job/file that doesn’t exist or has expired
`408`	The target page took too long to load (render endpoints only)
`429`	Per-minute rate limit exceeded, or the anonymous daily allowance is used up
`500`	Unexpected server-side failure

Error code reference

Status	Code	When it happens
`400`	(string message)	Missing/invalid input — e.g. no `url`, an unsupported `format`, an unparseable target URL
`401`	`invalid_api_key`	The API key is malformed, unknown, or revoked
`401`	`unauthorized`	An account-only route was called without a valid session or key
`402`	`insufficient_credits`	Your credit balance is below this request’s cost. Response includes `creditsRequired`
`404`	`unknown_endpoint`	No route matches this method + path under `/v1`
`404`	(string message)	A crawl `jobId` or a generated file has expired or never existed
`408`	(string message)	`/url-to-pdf` or `/screenshot` timed out waiting for the target page to render
`429`	`rate_limited`	You exceeded your plan’s requests-per-minute limit
`429`	`free_quota_exhausted`	An anonymous caller used up the 10-credit daily allowance for their IP
`500`	`caller_unresolved`	Internal wiring error — not something a valid request should trigger. Contact support if you see this
`500`	(string message)	An unexpected failure while processing the request

Retrying

Status	Retryable?
`400`, `401`, `402`, `404`	No — fix the request, credential, or balance first
`408`	Yes — often transient on a slow target page
`429`	Yes, after backing off. Honor the `RateLimit-Reset` header (seconds) rather than retrying immediately
`500`	Yes, with backoff — these are unexpected

Calling through the website’s own proxy at pocketutils.com/api/v1 (instead of api.pocketutils.com directly) adds one more possible failure: a 502 with { "success": false, "error": "Proxy Service Error", "message": "...", "details": "..." } if the proxy itself can’t reach the API. Direct integrations against api.pocketutils.com never see this shape.

Authentication

Avoid 401 errors before they happen.

Rate Limits & Credits

Avoid 429 and 402 errors before they happen.

Getting Started

API Reference

Platform-level errors

Endpoint-level errors

Status codes

Error code reference

Retrying

Authentication

Rate Limits & Credits

​Platform-level errors

​Endpoint-level errors

​Status codes

​Error code reference

​Retrying

Authentication

Rate Limits & Credits

Platform-level errors

Endpoint-level errors

Status codes

Error code reference

Retrying