Errors

Every error from the Renduo API follows the same shape, so you can handle them with one code path.

The error shape

{
  "error": "QUOTA_EXCEEDED",
  "message": "You reached the limit of 100 PDFs for the plan Free for period 2026-08.",
  "details": { "plan": "free", "period": "2026-08", "limit": 100, "used": 100 },
  "requestId": "req_..."
}

Field	Type	Description
`error`	string	Machine-readable code — stable, use it in your logic.
`message`	string	Human-readable explanation.
`details`	object, optional	Extra structured context (plan limits, validation errors).
`requestId`	string	Correlate with support requests.

Error codes

Codes are grouped by HTTP status. A details field is included where the extra context is useful.

400 — Bad request

Code	Description
`VALIDATION_ERROR`	The request body failed validation (Zod). `details` holds the issues.
`TEMPLATE_NOT_FOUND`	The template (or the pinned version) does not exist in your organization.
`BUNDLE_TOO_LARGE`	The bundle exceeds the maximum size (5 MB default).
`DOCUMENT_TOO_LARGE`	The generated document has more than 100 pages — a cost guardrail, not a technical limit. See Plans & limits for why.
`ASSET_NOT_FOUND`	A declared asset does not exist in your organization (surfaces at push time).
`ASSET_TYPE_UNSUPPORTED`	The uploaded asset type is not in the allowed list.

401 / 403 — Authentication & authorization

Code	Description
`UNAUTHORIZED`	Missing or invalid API key.
`FORBIDDEN`	The key is valid but lacks the required scope for this action.

402 — Quota exhausted

Code	Description
`QUOTA_EXCEEDED`	PDF quota of the period exhausted (Free: hard stop; paid plans accumulate overage instead).
`ASSET_QUOTA_EXCEEDED`	Asset storage or count quota of the plan exhausted.

404 — Not found

Code	Description
`NOT_FOUND`	The resource or route does not exist.
`TEMPLATE_NOT_FOUND`	The template (or the pinned version) does not exist.

409 — Conflict

Code	Description
`VERSION_NOT_ACTIVATABLE`	You tried to roll back to a version that never finished publishing (`pending` or `failed`). Only `active` and `disabled` versions can be activated.

413 — Payload too large

Code	Description
`BUNDLE_TOO_LARGE`	The baked shell (bundle + inlined assets) exceeds the maximum size.
`ASSET_TOO_LARGE`	The uploaded asset exceeds 2 MB.

429 — Rate limit

Code	Description
`RATE_LIMIT_EXCEEDED`	The global rate limit (100 requests/minute) was exceeded. The editor ephemeral render uses `QUOTA_EXCEEDED` for its per-organization budget.

500 / 502 / 504 — Server-side

Code	Description
`INTERNAL_ERROR`	An unexpected error. Retry, or contact support with `requestId`.
`RENDER_ERROR`	The component threw while rendering in the sandbox.
`GENERATION_TIMEOUT`	The render exceeded the timeout (10 s sync, 15 s async).
`TEMPLATE_UPLOAD_FAILED`	The bundle/shell could not be uploaded to object storage — the version was marked `failed`.
`ASSET_UPLOAD_FAILED`	The asset could not be uploaded to object storage.

503 — Temporarily at capacity

Code	Description
`SERVICE_BUSY`	The renderer is briefly out of capacity under a burst of concurrent requests. Already retried internally with backoff before this is returned — safe to retry, nothing to fix on your side.

These codes exist in the type contract for future use and are not currently emitted by the API: BUNDLE_NOT_FOUND, API_KEY_NOT_FOUND, ENVIRONMENT_NOT_FOUND, MEMBER_NOT_FOUND, ALREADY_EXISTS, LAST_ADMIN.

Handling errors in practice

Check error (not the HTTP status alone) — two codes share the same status (e.g. VALIDATION_ERROR and BUNDLE_TOO_LARGE are both 400).
Log requestId on every failure — it's the fastest path to support.
For QUOTA_EXCEEDED on Free, upgrade in the dashboard.
For RENDER_ERROR, the message usually points at a component exception — reproduce locally with the playground before re-pushing.
For SERVICE_BUSY, retry with a short backoff (e.g. 1-3 s) — it's not caused by anything in your request or component.