Error Codes

When an error occurs, the API returns a JSON response with an error field.

Error Response Format

{
  "error": "error message here"
}

Some errors include additional fields:

{
  "error": "monthly quota exceeded",
  "limit": 5000,
  "used": 5000,
  "resetAt": 1706745600,
  "upgrade": "Upgrade your plan to get more screenshots"
}

Error Reference

400

Bad Request

The request body is invalid or missing required parameters.

Example messages:

  • url is required
  • invalid url format
  • url must use http or https scheme
  • url must have a host
  • invalid JSON body
  • format must be png, jpeg, webp, or pdf
  • quality must be between 1 and 100
  • width must be between 1 and 4096
  • height must be between 1 and 4096
401

Unauthorized

Authentication failed.

Example messages:

  • missing API key
  • invalid API key
  • API key has been revoked
402

Payment Required

Monthly quota has been exceeded.

Example messages:

  • monthly quota exceeded
405

Method Not Allowed

The HTTP method is not supported.

Example messages:

  • method not allowed
429

Too Many Requests

Rate limit has been exceeded.

Example messages:

  • rate limit exceeded
502

Bad Gateway

The screenshot capture failed.

Example messages:

  • screenshot failed: timeout
  • screenshot failed: page not found
  • screenshot failed: connection refused

Troubleshooting

400 Bad Request

  • Verify your JSON syntax is valid
  • Check that url is a valid HTTP/HTTPS URL
  • Ensure parameter values are within allowed ranges

401 Unauthorized

  • Check that you're including the X-API-Key header
  • Verify your API key is correct and hasn't been revoked
  • Create a new API key if needed

402 Payment Required

  • Check your usage in the dashboard
  • Wait for your quota to reset at the start of the next billing period
  • Upgrade your plan for more screenshots

429 Too Many Requests

  • Slow down your request rate
  • Implement exponential backoff
  • Check the X-RateLimit-Reset header for when to retry

502 Bad Gateway

  • The target URL may be down or blocking requests
  • Try again in a few seconds
  • Check if the URL is accessible from a browser