Errors and how to recover

Every error is JSON with two fields:

  • error: the same shape for every error. Branch on error.code, never on message text.
  • detail: the specifics of this error (unchanged from before error existed). Where there is something to act on, it is an object.
{
  "error": {
    "code": "no_capacity",
    "message": "Every RTX 4090 is rented out right now; nothing was created. Join the waitlist to hear the moment there is room, or write to support@green-compute.com for more capacity.",
    "retryable": true,
    "retry_after_seconds": 60
  },
  "detail": { "code": "no_capacity", "requested_gpus": 1, "...": "..." }
}

error.message is a plain sentence saying what happened and what to do next, fit to show a person. error.retryable says whether sending the same request again later can succeed; if so, wait error.retry_after_seconds (also in the Retry-After header) when it is given.

/openapi.json describes this body as ErrorResponse (ValidationErrorResponse for 422) and lists, for each endpoint, the statuses it can return and the codes each may carry. It also declares how to authenticate (bearerAuth, or apiKeyHeader for X-API-Key) on every endpoint that needs a key; the public ones say security: [].

Error codes

On the terminal WebSocket, there is no HTTP status to read: an error arrives as a text message {"type": "error", "code": "…", "message": "…"}, then the connection closes with code 4000 + the status below (4401, 4409, 4429, 4503, …).

error.codeStatusMeaningRetry the same request?
gpu_unavailable400None of the GPU models asked for is offered; detail.available lists those that are.no
invalid_request400The request can't be done as sent; message says why. From /v1, also when the model itself refused the request (its reason in message, its status in detail.upstream_status; a 413 or 422 keeps that status), or it asks for something the model doesn't support, such as automatic tool choice.no; change the request
invalid_cursor400The paging cursor isn't one the API gave out, or was changed.no; send the previous page's X-Next-Cursor unchanged, or start again without one
challenge_invalid400The wallet sign-in message is unknown, already used or expired; request a new challenge.no
unauthenticated401The API key is missing or not valid.no
api_key_expired401The API key is past its expires_at; error.message says when. Create a new key under Settings (or with another key). Rentals it started keep running.no; use a new key
signature_invalid401The wallet signature doesn't match the sign-in message; request a new challenge and sign it unchanged.no
terminal_ticket_invalid401The terminal ticket is unknown, already used, expired (they last 60 seconds) or for another rental or API key. On the terminal WebSocket: close code 4401.no; request a new ticket
insufficient_balance402The balance doesn't cover an hour of what you're starting.no
approval_required403This change needs a signature from a wallet that already signs in to the account; detail.sign_with lists them.no
forbidden403This key or account may not do this.no
key_limit403The key is at one of its limits (rentals at once, or spend per 24 hours).no
unrestricted_key_required403Raising or clearing an account limit needs a key with full access and no limits or expiry of its own, such as the website's; detail.loosening names the fields. Any full-access key may lower a limit.no; use such a key, or Settings
account_spend_limit_reached403The account, every key together, reached the spend limit per 24 hours you set; running rentals are paused too, and can't be resumed until it's under the limit. detail has daily_spend_limit_usd and spent_last_24h_usd.no; wait for earlier spending to leave the 24-hour window, or raise the limit
account_rental_limit_reached403The account has as many rentals running as the limit you set (detail.max_active_rentals, detail.active_rentals).no; stop one or raise the limit
new_account_limit403A wallet account's first 7 days: at most 2 rentals at once and $50 of spend per 24 hours. Paying in $20 in crypto (TAO, alpha, USDC or USDT) ends it at once: detail.lifts_after_deposit_usd and detail.deposited_usd say how far along you are, and detail.hint how much more. Adding an email on the website ends it too; detail.until says when it ends anyway.no
scope_required403The key lacks a scope; detail.required_scope names it.no
wallet_blocked403This wallet can't be used with Green Compute; contact support@green-compute.com.no
wallet_sign_in_off403This wallet is linked to an account to pay in, not to sign in; sign in another way and turn wallet sign-in on under Billing > Verified wallets.no
not_found404No such resource on this account.no
model_not_found404No model by that name, id or address that this key may use; GET /v1/models lists the ones it can call.no
unknown_endpoint404No such endpoint; check the path against /openapi.json.no
method_not_allowed405That HTTP method isn't used on this path.no
terminal_idle408Terminal WebSocket only (close code 4408): closed after 15 minutes with no input and no output.no; open a new terminal
active_deployments409Stop the running rentals and models first.no
conflict409The resource's current state doesn't allow this, or (creating a secret) the name is taken: detail.secret_id is the one that has it.no
account_busy409Another rental is being started for this account right now: an account with a limit on rentals at once (its own, or a new wallet account's) starts them one at a time. Nothing was created.yes, after retry_after_seconds (2)
idempotency_in_progress409A request with this Idempotency-Key is still running.yes
model_not_ready409The model has a replica starting and none ready yet.yes, after retry_after_seconds (30)
model_not_running409Your model isn't running: it paused after 30 minutes without requests (resume it: POST /platform/deployments/{id}/resume), or its last deployment ended (deploy it again). detail.deployment_id names it, detail.paused says which.no; resume or redeploy it first
terminal_session_limit410Terminal WebSocket only (close code 4410): the terminal reached its 4-hour limit.no; open a new terminal
idempotency_key_reused422This Idempotency-Key was used with a different body.no
validation_error422Fields are missing or invalid; detail lists each one (loc is where, msg why). Also: more GPUs than one machine has (detail[0].ctx.le is the most, 8), a secret name you don't have, or a limit below 1 or negative offset; for inference, a request outside what it may ask for, such as empty messages or a max_tokens above the model's limit.no
auth_throttled429Too many failed API-key checks from this address; fix the key, then wait.no
rate_limited429Too many requests with this API key (20 a second on average, bursts of 40, or a per-endpoint limit), or (on /v1) the account already has 8 requests in progress at once to shared models (detail.limit, detail.in_flight; your own private models aren't limited); wait retry_after_seconds. The X-RateLimit-* headers say where the key stands: see Limits.yes
too_many_invoices429Too many unpaid crypto invoices are open.no
terminal_limit429Too many terminals are open: at most 3 per account at once, and a few per machine. Also close code 4429 on the terminal WebSocket.yes, once one is closed
server_error500Something failed on our side.yes
not_implemented501This endpoint is turned off (such as GET /registry/auth: there is no customer image registry; rentals pull public images by name).no
upstream_error502The model is up but failed on this request; message has its reason. Sent with x-should-retry: false, so OpenAI's SDKs don't retry it by themselves.no; a shorter request or fewer tokens may work
no_capacity503No GPU that fits is free; nothing was created. Join the waitlist (capacity alerts), retry after retry_after_seconds, or ask the team for more.yes
screening_unavailable503New wallets can't be checked right now; request a new challenge and try again in a few minutes.no
model_unavailable503The model exists but no replica can answer right now: its health check fails, its machine isn't reporting, a new replica is being started, or every replica has as many requests in progress as it takes. It comes back by itself.yes, after retry_after_seconds (30; 5 when only the connection dropped; 2 when it is at capacity)
unavailable503Temporarily unavailable.yes
exec_unknown504A command was sent to a rental but no answer came back in time: it may or may not have run. Check before running it again.no
upstream_timeout504The model is up but didn't finish this request in time (120 s without an answer when not streamed). Sent with x-should-retry: false.no; stream it ("stream": true) or ask for fewer tokens

By status

StatusWhenWhat to do
400A request is invalid, for example no requested GPU model exists in the fleet, or the model refused an inference request.Read detail. For GPUs, detail.available lists the ids you can use. For inference, error.message has the model's reason.
401The API key is missing, wrong or expired (api_key_expired), or a wallet sign-in's signature doesn't match.Send Authorization: Bearer <key>. Create a key under Settings, or get one by signing in with a wallet.
402Your balance is below one hour of the price of the rental or private model you're starting.Add credit on Billing, or over the API with crypto. detail gives the exact amounts.
403Your key can't access that resource, or its scopes don't allow the request (detail.required_scope names the scope it needs). At a key's limits, key_limit; at the account's own, account_spend_limit_reached or account_rental_limit_reached; raising an account limit with a key that has limits or an expiry of its own, unrestricted_key_required; for a new wallet account, new_account_limit; for a wallet that failed sanctions screening, wallet_blocked.Use a key from the account that owns it, or one with that scope. For a limit, stop a rental, wait for earlier spending to leave the 24-hour window, or raise it (account limits: PUT /platform/account/limits). For new_account_limit, stop a rental, pay in the rest of $20 in crypto, or wait until detail.until.
404The deployment or workload doesn't exist, or isn't yours. On /ssh, the pod isn't ready yet. On /v1, model_not_found: no such model for your key.Check the id; for /ssh, wait for state: "ready"; for a model, use an id from GET /v1/models.
409The action conflicts with the current state: resuming a pod whose machine is full, a retry sent while the first request with the same Idempotency-Key is still running, a secret name you already use, (account_busy) another rental being started at the same moment on an account with a limit on rentals at once, or on /v1 a model that is starting (model_not_ready) or not running (model_not_running).Read detail; when retryable, wait for Retry-After and retry. For a secret, replace its value with PUT /platform/secrets/{detail.secret_id}. For model_not_running, resume or redeploy the model.
422The request body or a query parameter doesn't match the schema (including gpu_count above 8, an unknown secret name, or a limit below 1; on /v1, also values no model accepts, such as empty messages), or an Idempotency-Key was reused with a different body.detail lists each bad field and why; use a new key for a different request.
429Rate limit: every API key may send 20 requests a second on average to /platform/… and /mcp, in bursts of 40, and some calls have their own (for example 30 creates per minute per key; see Limits); or five unpaid crypto invoices already open.Wait the number of seconds in the Retry-After header, then retry; watch X-RateLimit-Remaining to stay under it. For invoices, pay or let one expire, or pay from a verified wallet.
502On /v1, upstream_error: the model is up but failed on this request.Change the request (shorter, fewer tokens); if it keeps happening, write to support@green-compute.com.
503detail.code is no_capacity: every GPU this deployment could run on is rented out right now, or no single machine has room for the GPUs it needs together. Nothing was created. On /v1, model_unavailable: no replica of the model can answer right now.Join the waitlist (POST /platform/capacity-alerts) to hear when there is room, or wait the seconds in Retry-After (also detail.retry_after_seconds) and resend the same request. For more capacity, write to support@green-compute.com. A model comes back by itself: retry after Retry-After.
504On /v1, upstream_timeout: the model didn't finish the request in time.Stream it, or ask for fewer tokens.

The three you will see most

503 — rented out

{
  "detail": {
    "code": "no_capacity",
    "message": "every RTX 4090 is rented out right now; nothing was created. Join the waitlist to hear the moment there is room, or write to support@green-compute.com for more capacity",
    "gpu_models": ["rtx4090"],
    "requested_gpus": 1,
    "retry_after_seconds": 60,
    "waitlist": "POST /platform/capacity-alerts",
    "contact": "support@green-compute.com",
    "hint": "nothing was created. POST /platform/capacity-alerts with this gpu_model and gpu_count to be told (email and a capacity.available event) when there is room, or resend after Retry-After; GET /platform/pricing says when a GPU's availability is no longer fully_rented. For more capacity, write to support@green-compute.com"
  }
}

Returned at once, with a Retry-After: 60 header, when the GPUs exist but are all in use (that GPU's availability is fully_rented), or when some are free but not enough together on one machine (message says which). It never says how many are free. This is "busy", as distinct from the 400 below, which is "never". A 503 creates nothing, so resending the same request, with the same Idempotency-Key if you use one, is safe; joining the waitlist saves you polling.

400 — GPU not available

{
  "detail": {
    "message": "none of the requested GPU models are available to rent",
    "requested": ["h100"],
    "available": ["rtx4090"],
    "hint": "set supported_gpu_models to one of `available` (any spelling); see GET /platform/pricing"
  }
}

This is returned immediately when you start the deployment, both for a GPU we don't offer and for one with no machine online right now, so you never wait on a rental that could never be placed. available is the same list as GET /platform/nodes/supported. A GPU that is on that list but fully rented gives the 503 above instead.

402 — not enough balance

{
  "detail": {
    "message": "insufficient balance to start this rental",
    "required_cents": 40,
    "current_cents": 12,
    "rate_cents_per_hour": 40,
    "gpu_count": 1,
    "requested_instances": 1
  }
}

You need required_cents - current_cents more, here $0.28. Top up (the smallest top-up is $5), then send the request again. A 402 creates nothing, so this retry can't start a second rental; for other failures, such as timeouts, use an Idempotency-Key so a retry is safe.

A deployment that ends up failed

Read last_error on GET /platform/deployments/{id}. The most common causes:

  • No GPU it fits on came free. last_error starts no compatible miner capacity available after …: it was accepted, but every GPU it could use was taken before it was placed. Join the waitlist, or write to support@green-compute.com for more capacity.
  • The image doesn't exist or is private. Check the image name; only public images can be pulled.
  • The image's CUDA is too old for an RTX 5090. Use a CUDA 12.8+ image (see GPU rental).
  • SSH could not be set up in the image. A pod is only ready once its SSH server runs. Images without apt-get, apk, yum or dnf can't have one installed: use an Ubuntu/Debian/Alpine/CentOS-based image, or one with openssh-server preinstalled. A container whose own command exits at once fails the same way, with its last output in last_error.

A failed deployment is not billed.

A private model that was serving and then stopped answering its health checks (its model server crashed, or its machine went away) is redeployed automatically, up to 3 times an hour, when a deploy by you would be allowed then (credit for an hour, under your account's limits, a GPU free): its last_error ends Restarted automatically as deployment <id>, or says why it wasn't (Not restarted automatically: …). See Your own models.

A crypto payment that wasn't credited

A payment is matched to you by its exact invoice amount or by coming from a wallet you've verified. A different amount, a split payment, or one sent after the invoice expired isn't matched automatically. Verify the wallet you paid from, or request a review with the transaction hash: see If a payment isn't credited.