Errors and how to recover
Every error is JSON with two fields:
error: the same shape for every error. Branch onerror.code, never on message text.detail: the specifics of this error (unchanged from beforeerrorexisted). 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.code | Status | Meaning | Retry the same request? |
|---|---|---|---|
gpu_unavailable | 400 | None of the GPU models asked for is offered; detail.available lists those that are. | no |
invalid_request | 400 | The 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_cursor | 400 | The 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_invalid | 400 | The wallet sign-in message is unknown, already used or expired; request a new challenge. | no |
unauthenticated | 401 | The API key is missing or not valid. | no |
api_key_expired | 401 | The 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_invalid | 401 | The wallet signature doesn't match the sign-in message; request a new challenge and sign it unchanged. | no |
terminal_ticket_invalid | 401 | The 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_balance | 402 | The balance doesn't cover an hour of what you're starting. | no |
approval_required | 403 | This change needs a signature from a wallet that already signs in to the account; detail.sign_with lists them. | no |
forbidden | 403 | This key or account may not do this. | no |
key_limit | 403 | The key is at one of its limits (rentals at once, or spend per 24 hours). | no |
unrestricted_key_required | 403 | Raising 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_reached | 403 | The 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_reached | 403 | The 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_limit | 403 | A 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_required | 403 | The key lacks a scope; detail.required_scope names it. | no |
wallet_blocked | 403 | This wallet can't be used with Green Compute; contact support@green-compute.com. | no |
wallet_sign_in_off | 403 | This 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_found | 404 | No such resource on this account. | no |
model_not_found | 404 | No model by that name, id or address that this key may use; GET /v1/models lists the ones it can call. | no |
unknown_endpoint | 404 | No such endpoint; check the path against /openapi.json. | no |
method_not_allowed | 405 | That HTTP method isn't used on this path. | no |
terminal_idle | 408 | Terminal WebSocket only (close code 4408): closed after 15 minutes with no input and no output. | no; open a new terminal |
active_deployments | 409 | Stop the running rentals and models first. | no |
conflict | 409 | The 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_busy | 409 | Another 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_progress | 409 | A request with this Idempotency-Key is still running. | yes |
model_not_ready | 409 | The model has a replica starting and none ready yet. | yes, after retry_after_seconds (30) |
model_not_running | 409 | Your 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_limit | 410 | Terminal WebSocket only (close code 4410): the terminal reached its 4-hour limit. | no; open a new terminal |
idempotency_key_reused | 422 | This Idempotency-Key was used with a different body. | no |
validation_error | 422 | Fields 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_throttled | 429 | Too many failed API-key checks from this address; fix the key, then wait. | no |
rate_limited | 429 | Too 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_invoices | 429 | Too many unpaid crypto invoices are open. | no |
terminal_limit | 429 | Too 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_error | 500 | Something failed on our side. | yes |
not_implemented | 501 | This endpoint is turned off (such as GET /registry/auth: there is no customer image registry; rentals pull public images by name). | no |
upstream_error | 502 | The 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_capacity | 503 | No 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_unavailable | 503 | New wallets can't be checked right now; request a new challenge and try again in a few minutes. | no |
model_unavailable | 503 | The 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) |
unavailable | 503 | Temporarily unavailable. | yes |
exec_unknown | 504 | A 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_timeout | 504 | The 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
| Status | When | What to do |
|---|---|---|
400 | A 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. |
401 | The 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. |
402 | Your 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. |
403 | Your 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. |
404 | The 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. |
409 | The 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. |
422 | The 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. |
429 | Rate 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. |
502 | On /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. |
503 | detail.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. |
504 | On /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_errorstartsno 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
readyonce its SSH server runs. Images withoutapt-get,apk,yumordnfcan't have one installed: use an Ubuntu/Debian/Alpine/CentOS-based image, or one withopenssh-serverpreinstalled. A container whose own command exits at once fails the same way, with its last output inlast_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.
Green Compute