PandaStack
Reference

Errors

The exact JSON error bodies the PandaStack API returns, indexed by HTTP status and literal error string.

Every JSON error the API returns is flat. There is one required field, error, holding a human-readable message:

{ "error": "not found" }

Some responses add a detail sibling with a longer explanation:

{ "error": "unauthorized", "detail": "missing bearer token" }

Quota and rate-limit responses add context fields alongside error (for example workspace, tier, limit_per_hr). There is no code field, no nested error object, and no details object.

Branch on the HTTP status, not on the message text. The error string is written for humans and can change; the status is the contract.

Request IDs

The request ID is a response header, not a body field. Every API response carries X-Request-Id. If you send your own X-Request-Id (up to 64 characters), the API reuses it and forwards it to the compute node, so one ID correlates the whole request across services.

capture the request id
curl -sS -D- -o/dev/null https://api.pandastack.ai/v1/sandboxes \
  -H "Authorization: Bearer $PANDASTACK_API_KEY" | grep -i x-request-id

Status codes

HTTPLiteral error stringWhat it meansWhat to do
400git_url is required, name is required, cmd required, invalid json, env must be a string map, idle_timeout_seconds must be >= 60The request body is missing or malformedFix the payload; do not retry unchanged
401unauthorized (with detail: missing bearer token, invalid api token, or jwt required)No credential, an unknown API key, or a token-auth call on a JWT-only routeSend Authorization: Bearer $PANDASTACK_API_KEY; see Authentication
402free quota exceededFree credit is spent; the workspace is pausedAdd a payment method or upgrade — below
402monthly free credit exhaustedSame cap, enforced at the compute node with usage numbers attachedSame fix; the body includes credit_usd and cost_usd_used
402subscription not activeStripe subscription is past_due or canceled; running resources keep running, new creates are refusedUpdate payment; the body carries subscription_status
402org limit reached: your <tier> plan allows <n> org(s). Upgrade to create more.Plan org capUpgrade or reuse an existing org
402seat limit reached: your <tier> plan allows <n> member(s). Upgrade to invite more.Plan seat capUpgrade or remove a member
403account suspendedThe workspace is blocked from creating computeContact support (detail says so)
404not foundUnknown ID, or the resource belongs to another workspaceCheck the ID and your current org — Wrong workspace
404sandbox not found, sandbox not found or not runningThe sandbox ID does not exist on the node handling the requestRe-read GET /v1/sandboxes
404no code deployed yetFunction exists but has never been deployedPOST /v1/functions/{id}/deploy first
409sandbox not running (paused or hibernated) — resume/wake it firstYou called exec (or another guest operation) on a paused sandboxPOST /v1/sandboxes/{id}/resume. Hibernated sandboxes wake automatically
409managed sandbox: delete it from the feature that owns it (Databases or Apps)You called DELETE /v1/sandboxes/{id} on a sandbox owned by an app or databaseDelete the app or database instead
409volume already existsVolume name is takenPick another name
429rate limit: 50 req/burst, 25/sec sustained per workspacePer-workspace token bucket. Retry-After: 1 is setBack off and retry
429hourly create limit exceededToo many creates in the last hour; body has limit_per_hr and used_last_hrWait, or raise the workspace limit
429max sandboxes reachedConcurrent-sandbox cap; body has max and activeDelete idle sandboxes
429workspace resource quota exceededAggregate CPU or memory cap; body has cpu_used/cpu_max/memory_mb_used/memory_mb_maxDelete idle sandboxes or raise the cap
429monthly cpu-seconds quota exceeded, monthly budget exceededA workspace monthly ceiling you set was hitRaise the ceiling or wait for the monthly reset
500Varies — the underlying error textA bug or an unhandled failureA read can be retried once. Do not blindly retry a create: it may have gone through — list and reconcile. If it persists, report it with the X-Request-Id
502agent unreachableA node was chosen but the proxy could not reach it, possibly after the node received the request. Not a capacity refusalA read can be retried with backoff. For a create, list and reconcile before retrying
502agent error: … (on POST /v1/databases)A database create reports every error from the compute layer as a 502, with the original response after the colon — capacity refusals (503, 507) includedCheck GET /v1/databases for a new database before creating again. The SDKs do not retry database creates
503no compute capacity available (with detail)No node can take a new sandbox right now. Under load this is capacity. Sent with Retry-After: 5, before anything is createdRetry after Retry-After, with jitter — below
503sandbox host unavailable (with detail)The node running this sandbox is not responding. Sent with Retry-After: 15Retry after Retry-After; a managed database can be moved with POST /v1/databases/{id}/failover
503No JSON body (text/plain), no Retry-AfterThe load balancer in front of the API answered because an API server dropped the connection, possibly after it took the requestNot a capacity refusal. For a create, list and reconcile before retrying
507insufficient host memory for sandbox, insufficient host storage for sandboxThe chosen node refused the placement at its memory or disk gate, before creating anythingRetry with backoff; the scheduler picks again

402: free quota exceeded

The free tier includes $5.40 of credit per month. You get a warning email at 80%. At 100%, compute stops: running resources are paused and creates are refused. Nothing is deleted — your apps, databases, and data stay intact.

The control plane refuses the create before it reaches a node:

{
  "error": "free quota exceeded",
  "detail": "This account has used its free credit. Add a payment method to keep creating sandboxes."
}

Upgrading lifts the pause on the next reconcile, roughly a minute later. You do not need to recreate anything.

A paused app's URL answers 503 with an HTML page (not JSON), plus Retry-After: 3600 and an X-Pandastack-App: suspended header. See App serves 503.

503: no compute capacity available

Fleet capacity is bounded by memory. When no node can hold a new VM, the create is refused at routing time, before any node is asked to create it:

HTTP/1.1 503 Service Unavailable
Retry-After: 5
Content-Type: application/json

{
  "error": "no compute capacity available",
  "detail": "No compute node could be assigned right now. This is usually transient — retry in a few seconds."
}

This is transient, and because nothing was created, retrying is safe. Wait at least Retry-After, add random jitter so many clients do not come back at the same moment, and back off on repeats. The Python and TypeScript SDKs do this for you (see Retrying). If it repeats over minutes, delete sandboxes you are no longer using and contact support — see 503 on create.

This 503 does not mean the API is down. GET /healthz will still return 200 — the failure is placement, not the control plane.

Retrying

There is no retryable flag and no retry_after_sec field. Decide from the status and the Retry-After header:

  • Retry after Retry-After, with jitter: 429 from the per-workspace rate limiter (Retry-After: 1), and a JSON 503 that carries Retry-After (no compute capacity available: 5 s; sandbox host unavailable: 15 s).
  • Retry with backoff: 507.
  • Do not retry unchanged: 400, 401, 403, 404, 409, and a 429 without Retry-After (a quota — see the table for what clears it). The request, the resource state or your usage has to change first.
  • 402 clears when billing is sorted, not on retry.

The refusals in the first two groups are sent before anything is created, so they are safe to retry even for a create.

Creates are not idempotent. A create that ends in 500, 502, a 503 without Retry-After or without a JSON body, a timeout, or a dropped connection may have gone through, and retrying it can create a second sandbox. Tag creates with metadata you can recognise, then list and reconcile instead of blind-retrying. Reads (GET) can be retried with backoff.

The Python and TypeScript SDKs (0.10.0 and later) retry sandbox creates, forks and fork-trees refused with a 503 that carries Retry-After and a JSON error body, a 507, or a 429 that carries Retry-After. They never retry 500, 502, a 503 without those marks, a timeout or a dropped connection. Each wait is Retry-After plus a random jitter whose cap doubles from 1 s to 15 s (0.5 s plus the jitter for a 507, which has no Retry-After), so a run of capacity refusals waits 5–6 s, then up to 5–20 s per retry: about 5 to 9 retries in the default 60 seconds. After that they raise the last error. Set PANDASTACK_MAX_CREATE_RETRY_SECONDS (or the client option) to change the budget, or 0 to turn the retry off.

A refused create can therefore take up to the budget plus one request timeout. If you have your own deadline, set the budget below it. To give up early, pass an AbortSignal (TypeScript signal) or a threading.Event or multiprocessing.Event (Python cancel) to the create. Aborting in TypeScript also cancels an attempt in flight, and that attempt may still create a sandbox whose id you never get: tag creates with metadata and list to find it.

Reporting a problem

Include the X-Request-Id response header and the resource ID. Those two make a request traceable end to end. Email hello@pandastack.ai, or open an issue at github.com/pandastack-io/pandastack-ai/issues.

For symptom-first debugging, start at Troubleshooting.

On this page