Skip to content
ScreenshotDude

Core concepts

Status codes

Every HTTP status the API returns, what it means, and whether it's billed.

ScreenshotDude uses conventional HTTP status codes. Errors always have a JSON body:

{ "error": "Human-readable message" }

Success

Status Meaning Billed
200 OK Request succeeded. Body is the file (capture) or JSON. Yes (billable endpoints)
201 Created Used in request logs for async jobs that completed successfully. Never returned directly by an endpoint. Yes, on completion
202 Accepted Async request queued (is_async=true). Body: { "success": true, "job_id": "job_…", "status": "Queued" }. No

Client errors

Status Message examples Meaning
400 Bad Request url is required, Invalid URL, Unsupported format A parameter is missing or invalid, or the target is not allowed (e.g. private networks).
401 Unauthorized Invalid API Key Missing or unknown key.
401 Unauthorized Inactive API Key / Expired API Key Key is deactivated, archived or expired.
401 Unauthorized Rate limit exceeded: You've exceeded the per-second rate limit on your subscription Plan rate limit (also per-minute).
401 Unauthorized Rate limit exceeded for the API key: quota daily Per-key quota (total, daily, weekly, monthly).
402 Payment Required Payment required Subscription requires payment or is suspended.
402 Payment Required You have open invoices: … Unpaid invoices must be settled.
402 Payment Required Insufficient credits: 1 required, 0 available No balance and no overage available.
403 Forbidden This endpoint is not available on your plan. Upgrade to access it. Feature not on your plan (e.g. AI analysis on Free).
403 Forbidden IP temporarily blocked Too many failed authentication attempts from your IP.
404 Not Found Not Found Unknown endpoint or job, or the target page returned 404.
413 Payload Too Large Payload Too Large The result exceeds size limits (e.g. extremely tall full-page capture).

Rate limits return 401, not 429

ScreenshotDude returns 401 — not 429 — for both plan rate limits and per-key quotas. Distinguish them from authentication failures by the message, which always starts with Rate limit exceeded:

  • Rate limit exceeded: … — plan rate limit. Transient: retry after a short backoff.
  • Rate limit exceeded for the API key: quota … — per-key quota. Don't retry until the window frees up.

Server errors

Status Meaning
500 Internal Server Error Rendering failed, the target timed out, or an unexpected error occurred. Never billed. Retry with backoff, or use is_async=true for slow pages.

soft_fail

With soft_fail=true, every error is returned with HTTP 200 and the message in error:

{ "success": false, "error": "Invalid URL" }

This is useful for no-code tools that stop a workflow on non-2xx responses. Always check the error field when you use it.

Which requests are billed?

Only successful requests on billable endpoints. Every 4xx and 5xx is free — with one exception: the website crawler bills a 404 from the target site, because the crawl itself succeeded. See Credits & billing.