Docs

Errors

Every failure is structured JSON with error.code. Branch on the code, not the HTTP status text. Failed operations, 429s, and 402s are never billed.

Every failure returns { "error": { "code", "message" } } plus optional details. SDKs throw RelayPDFError with status, code, message, and retryAfter when present.

Shape

Same envelope on all endpoints.

Error JSON

{
  "error": {
    "code": "invalid_request",
    "message": "Provide exactly one of `html`, `url`, `markdown`, or `templateId`."
  }
}

Codes

Use error.code for branching. HTTP status is the transport; the code is the cause.

code	Typical HTTP	What to do
invalid_request	400	Check field names, types, and exclusive sources
unauthorized	401	Missing or unknown API key
account_suspended	403	Keys cannot be created or used
url_not_allowed	400	Private, loopback, or metadata host; or callbackUrl is not https
payload_too_large	413	Reduce HTML, files, or zip entries
not_found	404	Unknown job, file, or template
rate_limited	429	Honor Retry-After. Never billed
payment_required	402	Wallet empty — top up or enable auto-reload
quota_exceeded	402/429	Account limits; unbilled
render_failed	502	Chromium could not print the page; unbilled
processing_failed	502	PDF tool or job failed; unbilled
convert_unavailable	503	Document worker cold or unreachable; unbilled
ai_unavailable	503	Template generate backend unavailable; unbilled
storage_unavailable	503	Temporary file storage unavailable; unbilled
internal_error	500	Retry with backoff; unbilled

Billing

Failed operations, 429s, and 402s are never billed. Only a successful generation or conversion debits the wallet.

Docs hub →Node.js SDK →Playground →