PandaStack
FAQ

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 called DELETE /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 called exec (or another guest operation) on a paused sandbox. POST /v1/sandboxes/{id}/resume first. 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: 1 is set. It is the only one of the four that carries Retry-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 with POST /v1/databases/{id}/failover if 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.

On this page