Errors
ScreenFramed error response format, common status codes, and retry guidance.
Errors use a consistent JSON envelope:
json{ "error": { "code": "invalid_params", "message": "Invalid device. Must be one of: iphone-16-pro, macbook-pro-16, ipad-pro-m4, browser-macos, browser-windows" }}
Status codes
Invalid request
The API understood the request shape but rejected one or more parameters.
- Malformed JSON
- Missing url
- Invalid enum
- Invalid project id
Fix the request and send it again.
The request did not include valid authentication.
- Missing Authorization header
- Revoked key
- Expired signed URL
Refresh the key or mint a new signed URL.
The render was not started because the account did not have enough credits.
- Capture cost is greater than credits remaining
Add credits, upgrade the plan, or wait for renewal.
Forbidden scope
Scoped keys can only call endpoints included in their scope list.
- API key is missing the required scope
Use a key with the required scope.
Not found
The requested resource was not found for the authenticated account.
- Job
- project
- render
- or auth profile does not exist
Check the identifier and account ownership.
Rate limited
Rate limits are account-plan dependent and reset continuously.
- Too many requests in the current window
Wait for the Retry-After value before retrying.
Capture failed
The request was valid, but the capture or composition could not complete.
- Target page failed to load
- Selector not found
- Render could not complete
Retry only after fixing the target page or capture parameters.
Retry strategy
| Failure | Retry? | Guidance |
|---|---|---|
429 | Yes | Respect Retry-After and use backoff. |
| Network interruption | Yes | Retry with jitter. Use idempotent request payloads. |
400 validation | No | Fix parameters first. |
401 / 403 | No | Fix key, signature, or scope. |
402 | No | Add credits or reduce job cost. |
| Target page timeout | Maybe | Retry once, then investigate page load conditions or use async. |
Debug checklist
Add show_resolved_params: true while debugging composed requests.
Confirm the target URL is public unless you are using an auth profile.
Use selector for deterministic element capture before trying natural-language element detection.
Use async: true for slow dashboards and long full-page captures.