Responses and errors
What comes back, and what to do when it doesn't work.
Success responses
| Status | Meaning | Body |
|---|---|---|
200 | Screenshot captured | Raw image bytes (PNG or JPEG) |
Client errors
| Status | Meaning | When |
|---|---|---|
400 | Bad request | Missing url, invalid parameters |
401 | Unauthorised | Invalid or expired API key |
402 | Payment required | No API key provided (x402 flow), or insufficient balance |
429 | Rate limited | Too many requests. See rate limits |
Server errors
| Status | Meaning | When |
|---|---|---|
500 | Internal error | Browser crashed, page failed to load, or server issue |
504 | Timeout | Page took too long to render (30s limit) |
Error response format
All error responses return JSON:
{
"error": "Insufficient balance",
"code": "INSUFFICIENT_BALANCE",
"balanceMillicents": 0,
"costMillicents": 5000
}The 402 response (x402)
A 402 without an API key is not an error — it's the x402 payment negotiation. The response contains payment instructions that an agent can act on automatically. See agent payments for the full flow.