Common errors

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.

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.
• 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; the same condition can also surface as 502 no available compute node). The control plane is healthy; the failure is placement. Retry with exponential backoff, honoring Retry-After when present.

Two other 503s look similar but are not capacity:

• sandbox host unavailable — 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 with backoff on 429, 500, 502, 503, 507. Do not retry 400, 401, 403, 404, 409, 411 unchanged — the request or the resource state has to change first. Creates are not idempotent: if you lost a create's response, list and reconcile instead of blind-retrying. 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.