Skip to main content
The Screenshotly API uses standard HTTP status codes to indicate success or failure.

​
Status code overview

RangeMeaning
2xxThe request succeeded
4xxThe request failed due to client error
5xxThe request failed due to a server error (rare)

​
Error response format

All error responses return a JSON body with error and message fields: 
{
  "error": "Bad Request",
  "message": "The 'url' parameter is required."
}

​
Error codes

StatusErrorDescription
400Bad RequestThe request body is malformed or missing required parameters. Check that url is provided and all parameter types are correct.
401UnauthorizedYour API key is missing or invalid. Verify the screenshotly-api-key header.
403ForbiddenYour plan doesn’t include access to the requested feature (e.g., cookies/headers on the Free plan).
404Not FoundThe requested screenshot ID doesn’t exist.
422Unprocessable EntityThe parameters are valid types but contain invalid values (e.g., unsupported format, quality out of range).
429Too Many RequestsYou’ve exceeded your plan’s rate limit. Wait and retry. See rate limits.
500Internal Server ErrorSomething went wrong on our end. Retry the request. If it persists, contact support.

​
Handling errors

​
JavaScript SDK

const screenshot = await client.capture({
  url: 'https://example.com'
});

if (!screenshot.success) {
  console.error('Error:', screenshot.error);
  // Handle specific error types
}

​
HTTP status code check

response = requests.post(API_URL, headers=headers, json=payload)

if response.status_code == 401:
    print('Check your API key')
elif response.status_code == 429:
    print('Rate limited, retry later')
elif response.status_code >= 400:
    error = response.json()
    print(f"Error: {error['message']}")

​
Retry strategy

For transient errors (429 and 5xx), implement exponential backoff: 
async function captureWithRetry(client, options, maxRetries = 3) {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const result = await client.capture(options);

    if (result.success) return result;

    // Don't retry client errors (except 429)
    if (result.statusCode >= 400 && result.statusCode < 500 && result.statusCode !== 429) {
      throw new Error(result.error);
    }

    // Wait before retrying: 1s, 2s, 4s
    const delay = Math.pow(2, attempt) * 1000;
    await new Promise(resolve => setTimeout(resolve, delay));
  }

  throw new Error('Max retries exceeded');
}