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.
curl -sS -D- -o/dev/null https://api.pandastack.ai/v1/sandboxes \
-H "Authorization: Bearer $PANDASTACK_API_KEY" | grep -i x-request-idStatus codes
| HTTP | Literal error string | What it means | What to do |
|---|---|---|---|
| 400 | git_url is required, name is required, cmd required, invalid json, env must be a string map, idle_timeout_seconds must be >= 60 | The request body is missing or malformed | Fix the payload; do not retry unchanged |
| 401 | unauthorized (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 route | Send Authorization: Bearer $PANDASTACK_API_KEY; see Authentication |
| 402 | free quota exceeded | Free credit is spent; the workspace is paused | Add a payment method or upgrade — below |
| 402 | monthly free credit exhausted | Same cap, enforced at the compute node with usage numbers attached | Same fix; the body includes credit_usd and cost_usd_used |
| 402 | subscription not active | Stripe subscription is past_due or canceled; running resources keep running, new creates are refused | Update payment; the body carries subscription_status |
| 402 | org limit reached: your <tier> plan allows <n> org(s). Upgrade to create more. | Plan org cap | Upgrade or reuse an existing org |
| 402 | seat limit reached: your <tier> plan allows <n> member(s). Upgrade to invite more. | Plan seat cap | Upgrade or remove a member |
| 403 | account suspended | The workspace is blocked from creating compute | Contact support (detail says so) |
| 404 | not found | Unknown ID, or the resource belongs to another workspace | Check the ID and your current org — Wrong workspace |
| 404 | sandbox not found, sandbox not found or not running | The sandbox ID does not exist on the node handling the request | Re-read GET /v1/sandboxes |
| 404 | no code deployed yet | Function exists but has never been deployed | POST /v1/functions/{id}/deploy first |
| 409 | sandbox not running (paused or hibernated) — resume/wake it first | You called exec (or another guest operation) on a paused sandbox | POST /v1/sandboxes/{id}/resume. Hibernated sandboxes wake automatically |
| 409 | managed 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 database | Delete the app or database instead |
| 409 | volume already exists | Volume name is taken | Pick another name |
| 429 | rate limit: 50 req/burst, 25/sec sustained per workspace | Per-workspace token bucket. Retry-After: 1 is set | Back off and retry |
| 429 | hourly create limit exceeded | Too many creates in the last hour; body has limit_per_hr and used_last_hr | Wait, or raise the workspace limit |
| 429 | max sandboxes reached | Concurrent-sandbox cap; body has max and active | Delete idle sandboxes |
| 429 | workspace resource quota exceeded | Aggregate CPU or memory cap; body has cpu_used/cpu_max/memory_mb_used/memory_mb_max | Delete idle sandboxes or raise the cap |
| 429 | monthly cpu-seconds quota exceeded, monthly budget exceeded | A workspace monthly ceiling you set was hit | Raise the ceiling or wait for the monthly reset |
| 500 | Varies — the underlying error text | A bug or an unhandled failure | A 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 |
| 502 | agent unreachable | A node was chosen but the proxy could not reach it, possibly after the node received the request. Not a capacity refusal | A read can be retried with backoff. For a create, list and reconcile before retrying |
| 502 | agent 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) included | Check GET /v1/databases for a new database before creating again. The SDKs do not retry database creates |
| 503 | no 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 created | Retry after Retry-After, with jitter — below |
| 503 | sandbox host unavailable (with detail) | The node running this sandbox is not responding. Sent with Retry-After: 15 | Retry after Retry-After; a managed database can be moved with POST /v1/databases/{id}/failover |
| 503 | No JSON body (text/plain), no Retry-After | The load balancer in front of the API answered because an API server dropped the connection, possibly after it took the request | Not a capacity refusal. For a create, list and reconcile before retrying |
| 507 | insufficient host memory for sandbox, insufficient host storage for sandbox | The chosen node refused the placement at its memory or disk gate, before creating anything | Retry 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:429from the per-workspace rate limiter (Retry-After: 1), and a JSON503that carriesRetry-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 a429withoutRetry-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.