Reference

Errors

Every error code, what it means and what to do.

Every error has the same body. Branch on code, retry only when retryable is true, and look before acting again when outcome is unknown.

Code
{"error": {"code": "STALE_OBSERVATION", "message": "Input ran since your screenshot. Take a new screenshot first.",
  "request_id": "req_01jb7q0x9v2k8m4n6p3r", "retryable": false, "retry_after": null,
  "outcome": "not_applied", "docs_url": "https://docs.trykubi.com/errors#stale_observation", "details": {"acted_since": 2}}}

400 Bad request

Code	Meaning
`INVALID_ARGUMENT`	A field is missing, malformed or out of range (details.field, details.problem). Fix that field and resend.
`COORDINATE_OUT_OF_RANGE`	A point lies outside the coordinate space; it is rejected, never clamped. Use a point inside details.space.
`BATCH_TOO_LONG`	The batch would run past 28 s, inside the 30 s call limit. Split it into smaller batches.

401 Not signed in

Code	Meaning
`UNAUTHENTICATED`	The credential is missing, malformed, unknown, revoked or expired (details.reason). Send a valid key or token.

402 Payment needed

Code	Meaning
`QUOTA_EXCEEDED`	The organization is at its screen cap (details.screen_cap). Delete a screen, or a person asks support for a higher cap.
`PAYMENT_REQUIRED`	Payment failed. A person pays at details.pay_url.
`CREDIT_EXHAUSTED`	The usage credit that pays for disposable screens is used up (details.balance_usd). A person tops up at details.billing_url, or create a persistent screen.
`SUBSCRIPTION_REQUIRED`	Buying usage credit needs a paid persistent screen first. A person subscribes at details.billing_url.

403 Not allowed

Code	Meaning
`PERMISSION_DENIED`	The credential lacks details.needed, or is not bound to this screen. Use a credential that has it.
`HUMAN_ONLY`	Only a signed-in person (dashboard cookie) may call this. Ask a person to do it in the dashboard.
`CSRF_REJECTED`	A cookie request changed state without the dashboard's Origin. Send it from the dashboard, or use an API key.
`ORGANIZATION_SUSPENDED`	The organization is suspended. Stop and tell the user.
`ACCOUNT_PENDING`	The account is waiting for approval. Stop and tell the user.

404 Not found

Code	Meaning
`SCREEN_NOT_FOUND`	No such screen in your organization (the same answer for another organization's id). List screens for a valid id.
`NOT_FOUND`	No such operation, exec, key, app, export, template, snapshot or saved screenshot (saved ones go after 30 days). Check the id.
`FILE_NOT_FOUND`	Nothing at that path on the screen. List the folder with listFiles.

409 Conflict

Code	Meaning
`NO_CAPACITY`	No free machine for a new screen right now; nothing was charged. Retry after retry_after.
`STALE_OBSERVATION`	Input ran (anyone's, a person's in the live view included) or the screen restarted since your screenshot (details.acted_since, details.restarted). Take a new screenshot first.
`CONTROL_HELD`	A person has control of this screen, so nothing ran. Control ends when they release it, or after 5 minutes with no input from them. Wait retry_after seconds, then take a new screenshot before acting.
`SCREEN_NOT_RUNNING`	The screen is stopped, starting or stopping. Start it, or wait on its operation.
`OPERATION_IN_PROGRESS`	Another power operation runs on this screen. Wait on it, then retry.
`IDEMPOTENCY_KEY_IN_USE`	A request with this key is still running. Retry the same request.
`UNSUPPORTED_CAPABILITY`	This screen cannot do that (for example a screenless box). Use a screen that can.

413 Too large

Code	Meaning
`PAYLOAD_TOO_LARGE`	The body or file is over details.limit_bytes. Send less, or move big files through exec.

415 Wrong content type

Code	Meaning
`UNSUPPORTED_MEDIA_TYPE`	Wrong Content-Type. Send application/json (application/octet-stream for file uploads).

422 Cannot process

Code	Meaning
`IDEMPOTENCY_KEY_REUSED`	This key was used with a different body. Use a new key.
`SECRET_BLOCKED`	The input contains one of our API keys; nothing was typed or run. Remove the key and resend.
`URL_NOT_ALLOWED`	The URL is not public HTTPS: it resolves to a private or reserved address, or redirects. Use a public HTTPS URL.

429 Too many requests

Code	Meaning
`RATE_LIMITED`	Too many requests. Wait retry_after seconds.

500 Server error

Code	Meaning
`INTERNAL`	Our bug. Retry with the same Idempotency-Key.

503 Unavailable

Code	Meaning
`SCREEN_UNAVAILABLE`	The screen's host or desktop is not answering. Retry after retry_after.

504 Outcome unknown

Code	Meaning
`OUTCOME_UNKNOWN`	The work may or may not have happened. Look before acting; never resend blindly.

Drive the browser with Playwright Retries and idempotency