Errors answer a status and a JSON body with a stable code in error and a message for people. Some carry more fields.
{ "error": "sandbox_not_found", "message": "no sandbox named agent-9" }Match on error, not on the message, which may change. Every response carries a Nanite-Request-Id header; include it when you write to support.
When a refusal carries Retry-After, wait that many seconds before trying again. Filesystem errors use their own shape, with the error number as code.
Requests
invalid_argument
400. A field or query value is not valid: the body is not JSON, max_results is out of range, an env name breaks the rules. The message says which. Fix the request; trying it again as it is will not work.
invalid_name
400. A sandbox name is 1 to 63 lowercase letters, digits and dashes, starting with a letter or digit.
bad_request
400. A data route could not read the request, such as an exec env that is not KEY=VALUE or a checkpoint comment over 1024 bytes.
not_found
404. No such route, or no env variable or secret with this name.
sandbox_not_found
404. Your workspace has no sandbox with this name. Names are per workspace.
sandbox_held
409. The sandbox is held, so it stays stopped. Release it with {"hold": false} first.
schedule_not_found
404. The sandbox has no schedule with this id.
schedule_limit_exceeded
409. The sandbox has 20 schedules, the most it may. Remove one first.
name_taken
409. A sandbox with this name exists in your workspace, on a create or a rename. Pick another name, or delete the old one first.
method_not_allowed
405. The route exists but not with this method.
too_large
413. The body is over the limit of the route, such as a file write over 16 MiB.
Access
unauthorized
401. The Authorization header is missing, malformed, or holds a key that was revoked. See Authentication.
forbidden
403. The key has no access to sandboxes.
organization_suspended
403. While a workspace is suspended, its sandboxes cannot be made or changed. Write to support to bring it back.
Limits
sandbox_creation_rate_limited
429. A workspace can create 30 sandboxes a minute, and this one has created that many in the last minute. Wait for Retry-After, then make the next one.
{
"error": "sandbox_creation_rate_limited",
"message": "too many sandboxes created in the last minute",
"limit": 30,
"window_seconds": 60,
"retry_after_seconds": 60,
"current_count": 30,
"upgrade_url": null
}sandbox_limit_exceeded
429. A workspace keeps a set number of sandboxes, running or asleep, and this one has reached it. Delete a sandbox you no longer need. Carries limit and current_count.
concurrent_sandbox_limit_exceeded
429. A workspace can run a set number of sandboxes at once, and that many are running now. Answered to creates and to requests that would wake a sandbox. Each one stops after 30 idle seconds, which frees its place, so try again shortly or stop one you are done with. Carries limit and current_count.
Credits
insufficient_credits
402. Sandboxes spend credits as they run. With too few left, no sandbox can start or wake, and running ones are stopped. Their files are kept. An owner or admin can buy credits on the Billing page of the console; sandboxes can run again as soon as the purchase lands. Carries balance, in millionths of a credit. See Billing.
Capacity
node_unavailable
503 or 502. There was nowhere to start the sandbox right now, or the machine holding it stopped answering partway. With 503, nothing changed: wait for Retry-After and try again. With 502, the request may or may not have taken effect; check before you repeat anything that is not safe to run twice.
no_capacity
503. Every machine that runs sandboxes is full. Nothing was created. Try again after Retry-After.
capacity_access_required
403. Your workspace needs access before it can start sandboxes. Write to support.
capacity_start_not_enabled
403. Starting sandboxes needs purchased credits on this workspace. Buy credits in the console.
capacity_start_rate_limited
429. Your workspace has asked for new room to run sandboxes as often as it may today. Try again tomorrow, or write to support.
Capacity refusals also carry a Nanite-Capacity-Reason header with a finer reason. It is there for support; act on the status, the code and Retry-After.
Checkpoints
checkpoint_not_found
404. The sandbox has no checkpoint with this id. Checkpoints belong to one sandbox and go when it is deleted. List them to find the id.
checkpoint_failed
A line in a checkpoint stream. The disk could not be saved, so no checkpoint was made. The sandbox and its files are as they were. Try again in a minute.
restore_failed
A line in a restore stream. The checkpoint could not be put back, so the disk was not replaced. Try again in a minute. If it keeps happening, write to support with the request id.
not_supported
501. Checkpoints are not available for this sandbox right now. Write to support.
Preview URLs
urls_not_available
501. Preview URLs are turned off on this server, so url_settings cannot be changed.
Server
internal_error
500. Something broke on our side, and nothing was changed. Try again. If it keeps happening, write to support with the request id.