Common errors
The HTTP status codes you will actually hit — 401, 403, 404, 409, 411, 429, 503, 507 — what each one means, and the fastest fix.
Quick answers for the statuses that come up most. The authoritative list of every status and its exact JSON body is the error reference; for symptom-first debugging, start at Troubleshooting.
Branch on the HTTP status, not the message text. The error string is
written for humans and can change; the status is the contract.
401 Unauthorized
Missing or invalid credential. Send your API key as a bearer token:
curl https://api.pandastack.ai/v1/sandboxes \
-H "Authorization: Bearer $PANDASTACK_API_KEY"The detail field says which case you hit (missing bearer token,
invalid api token, or jwt required). The SDKs and CLI read the
PANDASTACK_API_KEY environment variable — the old PANDASTACK_TOKEN
name was removed and is never read. Verify with pandastack me.
403 Forbidden
The workspace is gated, not the request. Two cases:
account suspended— the workspace is blocked from creating compute (abuse mitigation). Contact support.- Signup/workspace provisioning refused — disposable or temporary email
domains (and similar throwaway-domain patterns) cannot provision a
workspace. The message is explicit:
disposable or temporary email addresses are not allowed — please use a permanent work or personal email. Sign up again with a permanent address.
404 Not Found
Either the ID is wrong, or the resource belongs to another workspace — the
API deliberately does not distinguish the two. Check the ID against
GET /v1/sandboxes (or the relevant list endpoint) and confirm your current
org with GET /v1/me. See
404 on a resource you know exists.
409 Conflict
The resource is in a state that refuses the operation:
managed sandbox: delete it from the feature that owns it— you calledDELETE /v1/sandboxes/{id}on a sandbox owned by an app or database. Delete the app or database instead; the platform tears down its sandbox.sandbox not running (paused or hibernated)— you calledexec(or another guest operation) on a paused sandbox.POST /v1/sandboxes/{id}/resumefirst. Hibernated sandboxes wake automatically on the next request.
411 Length Required
You sent a POST with no body. The edge rejects bodyless POSTs before they
reach the API, so parameterless endpoints — pause, resume, hibernate,
wake, fork, snapshots, database wake/failover/reset-credentials —
must be called with an empty JSON object and a content type:
curl -X POST https://api.pandastack.ai/v1/sandboxes/<id>/hibernate \
-H "Authorization: Bearer $PANDASTACK_API_KEY" \
-H "Content-Type: application/json" \
-d '{}'The SDKs and CLI do this for you; the 411 only appears with hand-rolled HTTP
clients that omit Content-Length.
429 Too Many Requests
Four distinct ceilings share this status — read the error string to tell
them apart:
- Rate limit (
50 req/burst, 25/sec sustained per workspace) — back off;Retry-After: 1is set. It is the only one of the four that carriesRetry-After; the three below do not, and a quick retry will not clear them. hourly create limit exceeded— wait, or raise the workspace limit.max sandboxes reached— delete idle sandboxes.workspace resource quota exceeded— aggregate CPU/RAM cap; the body carries the used and max values.
More in Limits and concurrency.
503 Service Unavailable
Capacity, not an outage — no compute node could take the request right now
(no compute capacity available, sent with Retry-After: 5). The control
plane is healthy; the failure is placement, and nothing was created. Retry
after Retry-After, with jitter and backoff. The Python and TypeScript SDKs
(0.10.0 and later) do this for sandbox creates automatically.
Two other 503s look similar but are not capacity:
sandbox host unavailable(Retry-After: 15) — the host running this sandbox is not responding; it usually recovers within a heartbeat. A managed database can be moved withPOST /v1/databases/{id}/failoverif it does not.- A 503 HTML page from an app URL means the app is paused (out of free credit) — see App serves 503.
507 Insufficient Storage
insufficient host memory for sandbox — one specific node refused the
placement on memory admission. Retry: the scheduler picks a different node.
Retrying, in one rule
Retry a 429 or a JSON 503 after its Retry-After, with jitter, but
only when the response carries that header: a 429 without it is a quota, and a
503 without it may follow a create that went through. Retry a 507 with
backoff. Those refusals are sent before anything is created. Do not retry
400, 401, 403, 404, 409, 411 unchanged — the request or the resource state
has to change first. Creates are not idempotent: after a 500, a 502, a
503 without Retry-After, a timeout or a lost response, list and reconcile
instead of blind-retrying (reads can simply be retried). Full guidance in the
error reference.
Still stuck?
Grab the X-Request-Id response header and the resource ID, then email
hello@pandastack.ai — those two make the request traceable end to end.
Networking and egress
Preview URL and app URL shapes, database TLS endpoints, what outbound traffic is allowed, and what is hard-blocked.
Troubleshooting
Symptoms you will actually hit on PandaStack, what causes them, and how to fix them — HTTP status codes, failed deploys, sandboxes that will not start, and database connection problems.