Every API error returns a JSON body with error (machine-readable code) and message (human-readable description). This page lists every error code, what triggers it, whether it is safe to retry, and how to respond.
| Error code | Trigger | Retry? | Action |
|---|
invalid_input | Request body failed validation | No | Fix the request payload and retry |
invalid_path_param | URL path parameter is missing or malformed | No | Fix the parameter value |
invalid_query_param | Query parameter is missing or out of range | No | Fix the query parameter |
invalid_header | A required header is missing or malformed | No | Fix the header value |
upload_blob_too_large | A single file exceeds the max blob size for the plan | No | Split or compress the file; see limits |
upload_session_too_large | Upload session exceeds max files or total bytes | No | Reduce the session size; see limits |
| Error code | Trigger | Retry? | Action |
|---|
missing_authorization | No Authorization header was provided | No | Add Authorization: Bearer pcak_... |
invalid_api_key | API key is malformed or uses the wrong prefix | No | Verify the key format starts with pcak_ |
| Error code | Trigger | Retry? | Action |
|---|
api_key_disabled | API key has been disabled | No | Enable the key in the dashboard or create a new one |
insufficient_permission | API key does not have the required permission | No | Use a key with the required scope |
upload_token_missing | X-Upload-Token header is required but not present | No | Include the upload token from session creation |
upload_token_invalid | X-Upload-Token is invalid or does not match the session | No | Verify you are using the correct token |
| Error code | Trigger | Retry? | Action |
|---|
deploy_not_found | Deploy ID does not exist | No | Verify the deploy ID |
deploy_version_not_found | Version ID does not exist or deploy has no matching version | No | Verify the version ID |
upload_session_not_found | Upload session ID does not exist | No | Verify the session ID or create a new session |
render_job_not_found | Render job ID does not exist | No | Verify the job ID |
render_job_output_not_found | Render job output has been deleted or never existed | No | Check if the job has completed |
pdf_asset_not_found | Managed PDF ID does not exist | No | Verify the PDF ID |
| Error code | Trigger | Retry? | Action |
|---|
deploy_slug_conflict | Deploy slug is already taken by another deploy in your account | No | Choose a different slug |
deploy_version_conflict | Upload session references a deploy version that cannot be updated | No | Create a new upload session |
upload_session_not_open | Upload session is already committed or expired | No | Create a new session |
upload_session_blob_not_referenced | Uploaded blob’s sha256 does not match any file in the session | No | Verify file descriptors match uploaded content |
render_job_not_failed | Cannot retry a render job that is not in failed state | No | Only retry jobs with status failed |
render_job_output_state_conflict | Output is in a state that prevents the requested operation | No | Check output state before retrying |
render_job_running | Operation conflicts with an active render job | Wait | Wait for the running job to complete |
idempotency_conflict | Same Idempotency-Key used with different request bodies | No | Use a unique key per unique request |
| Error code | Trigger | Retry? | Action |
|---|
upload_session_expired | Upload session TTL has elapsed (1 hour) | No | Create a new upload session |
render_job_output_expired | Render output has been deleted or retention period passed | No | Create a new render job with a fresh payload |
| Error code | Trigger | Retry? | Action |
|---|
not_implemented | Route is defined but not yet implemented | No | Check API documentation for availability |
| Error code | Trigger | Retry? | Action |
|---|
render_provider_not_configured | Render provider is not ready for the requested operation | Yes | Retry after a short delay; contact support if persistent |
These errors are documented in Plan Limits.
| Error code | Trigger | Retry? | Action |
|---|
upload_session_policy_limit_exceeded | Upload exceeds file count or byte limit | No | Reduce upload size or upgrade plan |
deploy_commit_policy_limit_exceeded | Deploy commit exceeds file count or byte limit | No | Reduce version size or upgrade plan |
storage_limit_exceeded | Account storage exceeds plan limit | No | Delete unused resources or upgrade plan |
deploy_commit_quota_exceeded | Deploy commits exceed monthly allowance | No | Wait for next period or upgrade plan |
render_job_quota_exceeded | Render jobs exceed monthly allowance | No | Wait for next period or upgrade plan |
render_time_quota_exceeded | Render time exceeds monthly allowance | No | Wait for next period or upgrade plan |
- Not retryable (
Retry? No): Fix the cause before retrying. Retrying without changes will produce the same error.
- Retryable (
Retry? Yes): Use exponential backoff with jitter (start at 1s, max 30s). These errors indicate transient conditions.
- Wait: The resource is busy. Poll at a reasonable interval (2–5s) until the state changes.
