Errors and retries
Error responses are JSON such as {"error":"subscription_required"}. Check both the HTTP status and error code. Avoid logging credentials, request headers, or sensitive workload output.
| Status / code | Action |
|---|---|
400 · invalid_size | Choose lite, small, medium, large, or xl from the returned sizes. |
409 · compute_capacity_exceeded | Choose a smaller size or stop an authorized container to release concurrent units. |
429 · compute_allowance_exhausted | Available runtime is used or reserved. Stop an authorized session to release unused runtime, upgrade through billing, or wait for the next UTC month. |
401 · not_authenticated | Supply a valid key or session. Revoke and replace exposed keys; do not retry with the same invalid credential. |
402 · subscription_required | Resolve compute access in web billing; retrying creation cannot grant access. |
403 · origin_required / origin_not_allowed | Browser mutations need a trusted Origin. Bearer calls can omit Origin; any supplied Origin must be trusted. |
400 · invalid_container_id / container_id_required / invalid_generation | Read current containers and supply the returned ID and exact creation timestamp. |
409 · container_limit_exceeded | Reuse a running container, or stop one only if the task authorizes it. Check account concurrency. |
| 429 · monthly start allowance exhausted | Wait for the next UTC month or change the plan through web billing. Stopping does not refund starts. |
404 · image_not_found / 409 · image_not_ready or image_not_available | Choose an advertised catalog image or wait for an owned custom image to become ready. |
413 · request_too_large / file_too_large | Reduce the request or use authorized SSH for files over 1 MiB. |
400 · invalid_file_path / 404 · file_not_found | Use a valid absolute path; create parent directories before writing. |
409 · not_regular_file / 403 · file_access_denied | Use a regular file and check permissions. Writes reject existing symlinks. |
409 · idempotency_key_conflict | Retry only with the original command and timeout; changed options need a new operation. |
429 · execution_history_limit | Wait for retained records to expire; do not create another container without checking the start budget. |
404 · execution_not_found | The record may be expired, missing or belong to another generation. Never relaunch an expired operation by retrying its old key. |
400 · invalid_cursor | Resume with the last received output sequence, within retained output. |
| 503 · service unavailable | Check status and retry reads with backoff. Reconcile mutations before retrying. Cleanup remains available during billing outages. |
Reconcile ambiguous mutations
Preview link creation is not idempotent. After a lost response, list active previews and revoke the unwanted grant before creating another. A 503 preview_reconciliation_required includes previewId; retry revocation for the same generation. A 429 preview_limit means eight grants are active; revoke one or wait for expiry. Read the preview contract before sharing a link.
For creation, reuse the original Idempotency-Key and body for up to 24 hours. Never choose an arbitrary container as the result of your request. For foreground execution, inspect effects before rerunning. For managed jobs, preserve the execution ID and key; reconcile matching options within the one-hour retention window. For file writes, read back the destination before another upload.
A command can return HTTP 200 and still fail. Check exitCode, timedOut, and outputTruncated, as described in Execute.