---
title: "Errors and exit codes"
description: "Failure taxonomy and billing consequences."
url: "https://www.promigence.ai/docs/errors"
site: "Promigence"
---

# Errors and exit codes

## Exit codes
| Exit | Meaning | Billing |
|---|---|---|
| 0 | Success | billed |
| 1 | Internal error on our side | not billed |
| 2 | Usage error, bad or missing arguments | not billed |
| 3 | Environment failure, the environment was at fault, not your command | not billed when our side shows it was ours |
| 4 | Task failure, your command exited non-zero | billed |
| 5 | Refused: the quote exceeds your spend cap | not billed |
| 6 | The snapshot is not verified | not billed |
| 7 | Missing or invalid API key | not billed |
| 8 | Not found | not billed |
| 9 | Unreachable | not billed |
| 10 | Rate limited | not billed |
| 11 | A --wait expired. Nothing was killed | unchanged |
| 12 | Partial, some environments did not start, or were stopped at the cap boundary | billed for what ran |
| 130 | Interrupted by the client | billed for what ran |

## Error codes
| Code | Category | HTTP | Exit | Billed | Meaning |
|---|---|---|---|---|---|
| fork_failed | env | 502 | 3 | no | The sandbox could not be started. |
| liveness_timeout | env | 502 | 3 | no | The sandbox did not answer its first command within {deadline_ms} ms. |
| probe_warm_failed | env | 502 | 3 | no | The sandbox failed its readiness check. |
| warm_ratio_failed | env | 502 | 3 | no | Verify cpu_ms {verify_cpu_ms} exceeds max(2 x {baseline_cpu_ms}, {baseline_cpu_ms} + 250). |
| verify_each_failed | env | 502 | 3 | no | Verify_each run failed in the fork (exit {exit_code}, digest {digest}). |
| toolchain_mismatch | env | 502 | 3 | no | Toolchain check `{argv}` in the fork gave digest {got}, the verified snapshot recorded {expected}. |
| guest_agent_lost | env | 502 | 3 | yes | The sandbox stopped responding. |
| oom_within_tier | env | 502 | 3 | no | The sandbox was killed by a memory fault on our side while under the tier's {tier_mib} MiB. |
| disk_full_within_tier | env | 502 | 3 | no | A storage fault on our side while the sandbox was under its {tier_disk_gib} GiB quota. |
| node_lost | env | 502 | 3 | no | The host running the sandbox became unreachable. |
| layer_integrity | env | 502 | 3 | no | The environment differs from the verified snapshot at {path}. |
| egress_unavailable | env | 502 | 3 | no | The sandbox's network egress check failed. |
| infra_timeout | env | 504 | 3 | yes | An internal deadline ({deadline_ms} ms) fired before your timeout. |
| preempted | preempt | 502 | 3 | no | The sandbox was stopped because the capacity it was running on had to be given back. |
| verify_did_not_cover | snapshot | 422 | 4 | yes | `{path}` is missing but was not under a verified path; the snapshot's verify did not cover it. |
| grader_failed | grader | 422 | 3 | yes | The grade could not be computed ({kind}). |
| nonzero_exit | task | 422 | 4 | no | Command exited {exit_code}. |
| grade_not_passed | task | 422 | 4 | no | The task completed and its grade did not pass (the grader exited {exit_code}). |
| task_timeout | task | 422 | 4 | yes | Command exceeded timeout_ms={timeout_ms}. |
| oom_over_tier | task | 422 | 4 | no | The process was killed for exceeding the tier's {tier_mib} MiB of memory. |
| disk_over_tier | task | 422 | 4 | no | The sandbox ran out of its {tier_disk_gib} GiB of disk. |
| shutdown_by_task | task | 422 | 4 | yes | The sandbox shut itself down ({kind}). |
| modified_by_task | task | 422 | 4 | yes | `{missing}` was removed or changed inside the sandbox; the snapshot's copy is intact. |
| cap_killed | cap | 402 | 12 | yes | Sandbox killed when its accrued spend reached the spend cap ({spend_cap}). |
| cap_exceeded | cap | 409 | 5 | no | Quote {max_cost} exceeds remaining spend cap {remaining}. |
| aborted_by_client | other | 200 | 130 | yes | Sandbox killed by the client. |
| expired | other | 200 | 12 | no | Sandbox timeout reached (counted from hand-off). |
| not_started | other | 200 | 12 | no | Sandbox not started: outside the spend cap. |
| superseded | other | 200 | 0 | no | Attempt 1 superseded by a successful retry. |
| usage | other | 400 | 2 | no | {detail}. |
| internal | other | 500 | 1 | no | Internal error. |
| auth | other | 401 | 7 | no | Missing or invalid API key. |
| forbidden | other | 403 | 7 | no | {detail}. |
| not_found | other | 404 | 8 | no | {kind} `{id}` not found. |
| unreachable | other | 503 | 9 | no | Cannot reach {url}. |
| rate_limited | other | 429 | 10 | no | Rate limited by {host}; retry after {retry_after_s} s. |
| timeout | other | 504 | 11 | no | Wait of {wait_timeout} expired; nothing was killed. |
| not_verified | other | 409 | 6 | no | Snapshot {snapshot_id} is not verified (build {build_id}: {state}). |
| pool_exhausted | env | 503 | 3 | no | No capacity free right now. |
| quota_exhausted | env | 503 | 3 | no | {region} is at capacity right now. |
| region_exhausted | env | 503 | 3 | no | {region} has no free capacity right now. |
| builder_unavailable | env | 503 | 3 | no | New snapshots cannot be built right now. |
| builder_busy | env | 503 | 3 | no | Snapshot builds are backed up; retry after {retry_after_s} s. |
| overloaded | env | 503 | 3 | no | The API is at capacity; retry in {retry_after_s} s. |
| tier_unavailable | env | 503 | 3 | no | The {tier} tier ({vcpus} vCPU / {mem_gib} GiB) is not available here yet. |
| snapshot_unavailable | env | 409 | 3 | no | Snapshot {snapshot_id} is no longer available: the capacity that held it was retired before it was saved. |
| capacity_limit | env | 409 | 3 | no | {requested} {tier} sandboxes at once is more than can run together; at most {max_at_once} at once. |
| build_timeout | other | 422 | 4 | no | The build ran past its {limit_min}-minute limit. |
| dockerfile_build_failed | other | 400 | 2 | yes | Your image could not be built from the Dockerfile: {detail}. |
| image_unresolvable | other | 422 | 2 | yes | `{image}` could not be resolved to a digest: {detail}. |
| registry_unavailable | env | 503 | 3 | no | `{image}` could not be resolved to a digest because its registry did not answer usably: {detail}. |
| enoent | other | 404 | 8 | no | `{argv0}` not found in the sandbox. |
| trial_credits_exhausted | cap | 402 | 5 | no | Trial credits left ({remaining}) do not cover this ({needed}). |
| credit_unclaimed | other | 402 | 5 | no | This account has free credit waiting to be claimed. |
| card_required | other | 402 | 5 | no | A card is required for new work since {effective_at}. |
| billing_unavailable | other | 503 | 5 | no | Card payments are not open yet. |
| concurrency_limit | other | 409 | 5 | no | {live} live + {requested} requested sandboxes is over your limit of {limit}. |
| egress_cap_reached | other | 403 | 10 | no | Monthly data-out cap reached: {used_gb} of {cap_gb} GB. |
| project_cap_reached | cap | 403 | 5 | no | Project {project} has {remaining} of its {limit} monthly cap left; this needs {needed}. |
| spend_limit_reached | cap | 402 | 5 | no | Today's spend limit {limit} has {remaining} left; this needs {needed}. |
| tier_over_plan | other | 403 | 2 | no | The {tier} tier ({vcpus} vCPU) is over the {limit} vCPU per-sandbox limit of your {plan} plan. |
| network_host_refused | other | 403 | 9 | no | {host} is not on this sandbox's allowed list, so the connection was refused. |
| network_policy_unsupported | env | 502 | 3 | yes | This sandbox asked to reach only {allow}, and that could not be applied where it was placed. |
| secrets_in_snapshot | other | 409 | 2 | no | Sandbox {sandbox_id} was given a secret's value, so a snapshot of it can contain that value. |
| secrets_unavailable | env | 503 | 3 | no | Secrets cannot be used right now. |
| secret_binding_unsupported | env | 502 | 3 | yes | A secret bound to a host could not be set up for this sandbox. |
| idempotency_key_reused | other | 409 | 2 | no | This Idempotency-Key was used for a different request. |
| idempotency_key_in_use | env | 409 | 3 | no | A request with this Idempotency-Key is still running. |
| repo_credentials_not_supported | other | 400 | 2 | yes | Credentials in repository URLs are not accepted ({field}). |
| account_exists | other | 409 | 7 | no | This email address has an account that signs in with {sign_in_with}. |
| invite_invalid | other | 403 | 7 | no | This invite code is not valid. |
| invite_required | other | 403 | 7 | no | New accounts need an invite code right now. |
| key_expired | other | 401 | 7 | no | This API key expired at {expired_at}. |