API RELIABILITY

Map HTTP responses to specific application actions

Check the status before reading success fields. Correct invalid requests, stop on authentication problems, back off after rate responses, and retry only transient conditions within a bounded policy.

2xx
Validate success body
4xx
Correct or authorize
5xx
Classify transient failure
Install:response.ok + response.status + safe body
Auth:SNAPSHOT_SITE_API_KEY
Get started for free
HTTP response handling
Snapshot Site themed screenshot API HTTP status codes illustration
Good fits
REST clients implementing normalized errors
Queue workers deciding retry eligibility
User interfaces displaying actionable job state
Support teams preparing safe diagnostics

Status is the start of classification

The same numeric family can contain different causes. Parse the response defensively, retain a safe diagnostic excerpt, and map provider detail into a stable application category.

1

Success responses

Validate expected structured fields and artifact availability before marking the job ready.

2

Caller responses

Fix invalid payload, unauthorized destination, or application input rather than retrying unchanged.

3

Authentication and rate

Correct secret configuration or delay and shape request volume according to the category.

4

Server and transport

Retry only plausible transient conditions with backoff, jitter, caps, and idempotent work.

Implementation workflow

Implement an HTTP response policy

1

Read status and body without assuming JSON

2

Map the response to a stable internal category

3

Choose terminal, user-action, or retryable behavior

4

Record attempt and stop at a defined retry budget

HTTP status handling example

JavaScript

Classify common response families

The client validates success and keeps retry decisions separate from user-facing messages.

const response = await fetch(endpoint, request);
const text = await response.text();
const body = safeJson(text);

if (response.ok) {
  return validateSuccess(body);
}

const category =
  response.status === 401 ? "authentication" :
  response.status === 429 ? "rate_limit" :
  response.status >= 500 ? "provider" :
  "request";

const retryable =
  response.status === 429 || response.status >= 500;

throw new CaptureError({ category, retryable, status: response.status });

HTTP success is not application readiness

A success status indicates that the request completed at the protocol level. The application still needs to validate expected fields, artifact availability, format, and storage. Marking a job ready before those checks can expose incomplete or malformed data.

Keep provider status separate from target content quality. A page can render successfully while showing a CAPTCHA, blank state, or application error.

Do not flatten client errors

A malformed request needs a code fix or corrected user input. Authentication failure needs secret or configuration work. Rate limiting needs lower pressure and delayed retry. Treating every client response as a generic failure makes the UI unhelpful and creates unsafe retry loops.

Normalize provider detail into internal categories that remain stable even if message wording changes.

Bound transient recovery

Transport and server failures may justify retry when another attempt can plausibly succeed. Use exponential backoff with jitter, cap attempts and job age, and make the logical capture idempotent. A timed-out request may have completed remotely, so storage must handle duplicate or late results safely.

Logs should include enough context for diagnosis without credentials, signed query parameters, private response bodies, or public artifact exposure.

The error handling guide covers full failure stages, while the rate-limit guide focuses on bounded concurrency and retry.

Screenshot API HTTP Status Codes FAQ

Which HTTP status means a screenshot succeeded?

A successful HTTP status is necessary but not sufficient. Validate the expected response fields and artifact before marking the application job ready.

Should every 4xx response be retried?

No. Invalid input and authorization problems usually require correction. A rate response is handled separately with delayed bounded retry.

How should 401 be handled?

Stop repeating the same request, verify secret injection and header configuration, and rotate the key if exposure is suspected.

What should happen after 429?

Reduce concurrency or request rate, honor retry guidance when present, and retry later with backoff, jitter, and a cap.

Are all 5xx responses safe to retry?

They may be transient, but retries still need idempotency, delay, a total budget, and awareness of whether the first attempt could have completed.

What if the error body is not JSON?

Read defensively and retain only a bounded safe excerpt in protected diagnostics. Proxies and upstream systems can return other formats.

How should status be shown to users?

Map it to an actionable application message without exposing API keys, internal endpoints, private URLs, or raw provider internals.

What belongs in a status log?

Keep internal job ID, operation, status, normalized category, attempt, timing, and safe target identity with sensitive values redacted.

Related resources

Snapshot Site HomeWebsite Screenshot APIScreenshot API ExamplesTypeScript SDKAPI DocumentationPricingError HandlingRate LimitsAPI TimeoutsAuthentication

Define status actions before adding retries

Map each response category to correction, delay, terminal failure, or escalation and test the policy with controlled fixtures.

Get started for freeRead the API docs