API reference

Errors and safe retries

Errors are JSON resources with a stable machine code, a human message, and optional structured details.

HTTPS API api-screenshot.com/v1 Bearer auth · JSON requests · private artifacts

Private development preview The contract is documented for integration planning. Production API routes currently return HTTP 503 and no live keys are being issued. OpenAPI 3.1 →

Error object

Response shape

Example json

{
  "error": {
    "code": "invalid_parameter",
    "message": "quality is available only for JPEG and WebP output.",
    "details": {
      "parameter": "quality"
    }
  }
}

HTTP semantics

Status codes

Status	Meaning	Retry?
400	Malformed transport-level request	Fix the request
401	Missing or invalid API key	Refresh credentials
403	Account does not have active access	Resolve account access
404	Screenshot resource not found for this account	Do not retry blindly
409	Idempotency conflict or concurrent state change	Reconcile request state
422	URL, JSON, header, or screenshot option is invalid	Fix the named field
429	Request, concurrency, or credit limit reached	Retry after backoff or reset
503	Preview gate or required dependency unavailable	Retry only with bounded backoff

Machine codes

Common error codes

Code	Cause
development_preview	Production API access is not enabled
invalid_api_key	Bearer credential is missing or invalid
invalid_json	Request body is not a JSON object
invalid_idempotency_key	Idempotency-Key is missing or outside its bounds
invalid_url	Target is not a valid HTTP or HTTPS URL
embedded_credentials	The target URL contains a username or password
blocked_target	Target resolves to a private, local, metadata, or special-use destination
unknown_parameter	Request contains a field the API does not accept
invalid_parameter	An option has the wrong type, value, or combination
idempotency_conflict	The same key was reused with different request data
not_found	The resource does not exist for the authenticated account

Reliability

Retry policy

Retry network failures, HTTP 429, and transient HTTP 503 with exponential backoff and jitter.
Reuse the same Idempotency-Key and identical body when retrying POST /v1/screenshots.
Do not retry validation, authentication, or idempotency-conflict errors without changing the underlying cause.
Cap attempts and retain X-Request-ID for support and tracing.