Errors
Use one shared failure model across the API
Parse the standard error shape first, classify by HTTP status, then choose a recovery path. This page is the canonical failure contract for rendering, accepted job follow up, and batch operations.
Where this page applies
Single render and follow up routes
POST /v1/pdf, GET /v1/pdf/jobs/:id, GET /v1/pdf/jobs/:id/file
Route specific failures use the same overall error fields, regardless of synchronous or accepted execution.
Batch create and retrieval routes
POST /v1/pdf/batch and /v1/pdf/batch/*
Overall failures use the shared shape, while batch status payloads can also include item level error details.
Default recovery posture
Fix most 4xx, back off on 429, retry bounded 5xx
Send Idempotency-Key on create routes whenever clients may retry.
Shared parse target
Always read statusCode, error, and message before route specific details.
Retry boundary
Retry unchanged requests only for 429 and transient 5xx responses.
Create safety
Use idempotency keys for single and batch create calls to prevent duplicate work.
Status Code Map
Map status codes to recovery decisions
These are the major failure statuses you should expect across single render, accepted job, and batch routes.
Shared status meanings
400 Bad Request
validation or contract failure
Fix request shape, invalid combinations, or malformed identifiers before retrying.
401 Unauthorized
credential failure
Credential is missing, invalid, expired, or otherwise not usable for this route family.
403 Forbidden
policy or entitlement block
Caller is recognized, but current plan, quota, or policy does not allow the operation.
404 Not Found
missing route resource
Job, item, or related resource is missing, expired from visible scope, or not owned by this caller context.
409 Conflict
idempotency or state conflict
Idempotency key reused with a different request body, or request already processing.
410 Gone
expired batch outputs
Batch outputs are outside retention and no longer downloadable.
413 Payload Too Large
size limit exceeded
Input or batch payload exceeds current plan limits; unchanged retries will fail.
429 Too Many Requests
rate or backlog pressure
Temporary pressure condition. Back off with jitter and honor Retry-After when present.
5xx
transient server fault
Unexpected server side failure; apply bounded retries with idempotency safe create behavior.
Retryability Guidance
Retry only when the condition can clear without request changes
Most 4xx responses require a fix before retry. Use controlled retries for 429 and transient 5xx only.
Operational retry policy
Retry statuses
429 and transient 5xx
Use exponential backoff with jitter and a max-attempt cap. Honor Retry-After when present.
No unchanged retry
400, 401, 403, 404, 409, 410, 413
Change input, credentials, account limits, or selected resource before another attempt.
Create route guardrail
Idempotency-Key on POST creates
Protect retries for POST /v1/pdf and POST /v1/pdf/batch so repeated attempts do not duplicate work.
Auth Failures
Separate credential failures from access policy failures
Handle 401 and 403 differently. They represent different fixes and should not share one retry path.
Auth failure triage
Bearer token/session failures
401 Unauthorized
Token missing, invalid, or expired. Refresh token or re-authenticate before retrying.
API key failures
401 Unauthorized
Missing or invalid X-API-Key, or key no longer valid for requested route usage.
Auth abuse cooldown
429 Too Many Requests
Login or auth-protection controls can return Retry-After. Wait for that window before retrying.
Policy denials
403 Forbidden
Caller is authenticated, but policy restrictions (for example bans or entitlement gates) block the action.
Limit Failures
Treat hard limits and temporary pressure as different recovery paths
Some limit failures need request or plan changes. Others can clear with time and controlled retries.
Limit classes
Payload size limits
413 Payload Too Large
Reduce source size, trim assets, or split batch inputs. Unchanged retries will not pass.
Quota and entitlement limits
403 Forbidden
Current quota, feature entitlement, or plan boundary prevents this action.
Backlog and rate pressure
429 Too Many Requests
Temporary pressure on API/backlog capacity. Retry with backoff, jitter, and request pacing.
Temporary service capacity
503 Service Unavailable
Service-side capacity or dependency condition; retry with bounded backoff and monitoring alerts.
Batch Item Failures
Handle item level failures separately from overall batch acceptance
A batch can be accepted while individual items later fail. Always read items[] before deciding how to recover.
Item level failure semantics
Item error detail
items[].error and items[].errorMessage
Item failures include a normalized code/message pair and can also include a raw error message string.
Retry metadata
items[].retryAttempt
Use retry attempt metadata to avoid duplicate client side requeue logic.
State driven recovery
queued, processing, completed, failed
Use item status as the primary signal. Do not rely on overall batch status alone.
For route specific contracts, see the batch rendering reference.
Next Steps
Connect this failure model to idempotency, lifecycle, and batch contracts
Need safe create retries?
Open idempotency concepts
Use same-key replay and conflict rules to keep retry loops duplicate-safe.
Need async recovery decisions?
Open jobs and lifecycle
Use state transitions to decide when to poll, wait, retry, or escalate.
Need batch endpoint contracts?
Open batch rendering reference
Review create, status, zip, cancel, and item retrieval route details.