Skip to Content
Podyard

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"
  }
}
FieldTypeDescription
codestringMachine-readable error code (stable across versions)
messagestringHuman-readable description
requestIdstringCorrelate with server logs
docsUrlstringLink to the relevant docs section

HTTP_STATUS_CODES

StatusMeaning
400Malformed request body or missing required field
401Missing or invalid API key
403Key is valid but lacks permission for this operation
404Resource not found
409Conflict (duplicate resource, idempotency key mismatch, state conflict)
413Payload too large (exceeds plan size limit)
422Valid syntax but semantically invalid (e.g., pod not in required state)
429Rate limit or quota exceeded
501Operation not implemented (engine gap)
500Internal 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-Key used with a different request body.
  • State conflict: operation requires a specific resource state (e.g., sleep on a pod that's not running).
  • 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., exec on a stopped pod)
  • sleep/wake called when sleepWake is 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 /fs on 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