Errors

GPU Forge uses standard HTTP status codes. Every refusal says why, and most say what to do next. A refusal of an action that costs money means nothing was rented and nothing was charged, unless the answer explicitly says otherwise (see 502 below).

#Error format

Most errors have a detail field. It is either a sentence:

{"detail": "no job 'job_000000000000'"}

or an object with more fields:

{
  "detail": {
    "error": "another rental for this capability is already running",
    "capability_id": "cap_ab12cd34",
    "nothing_rented": true,
    "help": "A scale is renting for this capability right now. ... Try again in a moment."
  }
}

Fields you may find in an object detail:

Invalid request bodies (422) use a different shape that names each problem:

{
  "error": "the request body was not accepted",
  "problems": [
    {"field": "spec.min_vram_gb", "problem": "Input should be greater than or equal to 0", "you_sent": -1},
    {"field": "spec.min_vram_gbb", "problem": "Extra inputs are not permitted", "you_sent": 48,
     "expected": "Unknown field — check the spelling. GET /v1/help lists every accepted field."}
  ],
  "help": "GET /v1/help for every field, its units, and examples."
}

Values that may carry a secret (anything under secrets, SSH keys) are never echoed back in you_sent.

A few refusals are returned as a top-level {"error": "...", ...} object without detail (for example a balance refusal raised at the moment of renting). Read detail first, then error.

#Status codes

#502 and machines that may be billing

A 502 from a call that rents or ends a machine needs care:

• On a rental (deploy, scale, POST /v1/deploy): if the body has "indeterminate": true, a machine may have been created and may be billing; "machine_exists": true means one certainly was. Do not retry: a retry can rent a second machine. Find it by the pod_id in the body with GET /v1/fleet/{pod_id}, and destroy it if you do not want it. Without indeterminate, the provider refused and nothing was rented.
• On a destroy: the provider has not yet confirmed the machine is gone. The request is saved and retried automatically, and the machine stays in your fleet until absence is confirmed. You can call destroy again safely.
• On a search: a 502 means every provider failed. If only some failed, you get 200 with their errors in provider_errors.

#Errors from ready programs

A job reports the program's own errors inside the job, not on POST /v1/jobs:

{"status": "failed", "status_code": 422, "error": "the program answered 422", "price_usd": 0.0,
 "result": {"error": "..."}}

A failed job is never charged. Common program answers:

A job that could not get a machine within 20 minutes fails with "error": "no machine of this program could be started in time; nothing was charged".

#Retrying safely

This page as Markdown, for tools and agents: /docs/errors.md