ERRORS
Complete error code reference for the Podyard API.
ERRORS
All errors use a consistent envelope:
{
"error": {
"code": "not_found",
"message": "Pod pod_01J... not found.",
"requestId": "req_01J...",
"docsUrl": "https://docs.podyard.dev/api/errors#not_found"
}
}| Field | Type | Description |
|---|---|---|
code | string | Machine-readable error code (stable across versions) |
message | string | Human-readable description |
requestId | string | Correlate with server logs |
docsUrl | string | Link to the relevant docs section |
HTTP_STATUS_CODES
| Status | Meaning |
|---|---|
400 | Malformed request body or missing required field |
401 | Missing or invalid API key |
403 | Key is valid but lacks permission for this operation |
404 | Resource not found |
409 | Conflict (duplicate resource, idempotency key mismatch, state conflict) |
413 | Payload too large (exceeds plan size limit) |
422 | Valid syntax but semantically invalid (e.g., pod not in required state) |
429 | Rate limit or quota exceeded |
501 | Operation not implemented (engine gap) |
500 | Internal server error |
ERROR_CODES
unauthorized — 401
Missing, malformed, or revoked API key.
{ "error": { "code": "unauthorized", "message": "Invalid or missing API key.", "requestId": "req_...", "docsUrl": "..." } }Fix: Check PODYARD_API_KEY is set and the key is not revoked.
forbidden — 403
Key is valid but the operation is not permitted (e.g., using a regular key to call a deployment-key-only endpoint).
Fix: Use the correct key type for the endpoint.
not_found — 404
The requested resource does not exist or is not visible to your key.
{ "error": { "code": "not_found", "message": "Pod pod_01J... not found.", "requestId": "req_...", "docsUrl": "..." } }Fix: Verify the ID is correct and the resource belongs to your account.
conflict — 409
One of:
- Idempotency key mismatch: same
Idempotency-Keyused with a different request body. - State conflict: operation requires a specific resource state (e.g.,
sleepon a pod that's notrunning). - Duplicate resource: e.g., creating a template with a name that already exists.
Fix: Check the message for specifics. For idempotency, use a fresh UUID for a new request.
payload_too_large — 413
The request payload exceeds the plan's size limit.
{ "error": { "code": "payload_too_large", "message": "File size 524288000 exceeds plan limit 268435456 bytes.", "requestId": "req_...", "docsUrl": "..." } }Fix: Reduce the payload or upgrade your plan. See Limits.
invalid_request — 422
The request is syntactically valid but semantically incorrect.
Common causes:
- Missing required field
- Invalid enum value (e.g.,
status: "foo") - Operation on a resource in the wrong state (e.g.,
execon astoppedpod) sleep/wakecalled whensleepWakeis disabled for the plan
Fix: Read the message — it always describes the specific problem.
rate_limited — 429
Your key has exceeded its rate limit.
{ "error": { "code": "rate_limited", "message": "Rate limit exceeded. Retry after 30 seconds.", "requestId": "req_...", "docsUrl": "..." } }The response also includes X-RateLimit-Remaining: 0 and X-RateLimit-Reset: <unix_timestamp>.
Fix: Wait until X-RateLimit-Reset, then retry. The SDK retries automatically. See Rate limits.
quota_exceeded — 429
A resource quota has been exhausted.
{ "error": { "code": "quota_exceeded", "message": "Concurrent pod limit (5) reached. Destroy a pod or upgrade your plan.", "requestId": "req_...", "docsUrl": "..." } }Fix: Destroy pods or snapshots to free capacity, or upgrade your plan.
not_implemented — 501
The operation is not yet supported by the engine. This is a Coming soon feature.
{ "error": { "code": "not_implemented", "message": "Directory listing is not yet supported.", "requestId": "req_...", "docsUrl": "..." } }Currently affected:
- Directory listing (
GET /fson a directory) - Engine-side snapshot list/delete (Podyard serves from its own store)
Fix: No action needed — this is a planned feature. The docsUrl links to the relevant "Coming soon" section.
internal_error — 500
An unexpected server error occurred.
{ "error": { "code": "internal_error", "message": "Internal server error. Please try again.", "requestId": "req_01J...", "docsUrl": "..." } }Fix: Retry the request. If the error persists, contact support with the requestId.
WHERE_TO_GO_NEXT
- API overview — base URL and conventions.
- Rate limits — how to handle 429s.