Reference

Errors

Synoppy uses standard HTTP status codes. Failed requests return a JSON body with success: false, a machine-readable code, and a human-readable error message.

{
  "success": false,
  "code": "RATE_LIMITED",
  "error": "Rate limit reached. Grab an API key for higher limits."
}

Status and code reference

400BAD_REQUEST

The request failed validation — a required field is missing or malformed. INVALID_URL and BLOCKED_HOST (private/loopback targets) also return 400.

401INVALID_KEY

Missing or invalid API key. Endpoints that always require a key (Extract, Classify, Crawl) return AUTH_REQUIRED for anonymous calls. See Authentication.

402NO_CREDITS

You are out of credits. Upgrade or wait for your monthly reset — see pricing.

415UNSUPPORTED_FORMAT

The target is a binary the engine doesn't read as a web page (e.g. a PDF). Read returns this instead of billing for unusable bytes.

429RATE_LIMITED

Too many anonymous requests. Add an API key for higher limits, or back off and retry using the Retry-After header.

502BAD_STATUS · TIMEOUT · MODEL_ERROR

The target site failed to respond, timed out, returned an unreadable page, or the extraction engine was briefly unavailable. Safe to retry.

503RENDER_UNAVAILABLE · NOT_CONFIGURED

A browser backend (Screenshot / JS render) or an AI model (self-hosted only) isn't available. Never billed.

Which codes each endpoint can return

On top of the universal 400, 401 INVALID_KEY, 402 NO_CREDITS, and 429, each endpoint can add:

ReadPOST /api/scrape

415 UNSUPPORTED_FORMAT (PDFs/binaries), 502 on upstream failure. No key required — anonymous is IP-rate-limited.

CrawlPOST /api/crawl

401 AUTH_REQUIRED (a key is always required), 502 on failure.

MapPOST /api/map

502 on failure. No key required.

ExtractPOST /api/extract

401 AUTH_REQUIRED (key required), 503 NOT_CONFIGURED (self-host), 502 on failure.

ClassifyPOST /api/classify

401 AUTH_REQUIRED (key required), 503 NOT_CONFIGURED (self-host), 502 on failure.

EnrichPOST /api/brand

502 on failure. No key required.

ImagesPOST /api/images

502 on failure. No key required.

ScreenshotPOST /api/screenshot

503 RENDER_UNAVAILABLE (no browser backend), 502 RENDER_FAILED. No key required.