Errors and rate limits

Error format

Every error response has the same JSON body. code is stable and meant for your code; message is for people and may change. docs_url links to the code's row below. details is present only for some codes: template errors include the Liquid line and column when they are known.

{
  "error": {
    "code": "rate_limited",
    "message": "Rate limit of 60 requests per minute exceeded. Retry in 42 seconds.",
    "docs_url": "https://castpdf.com/docs/errors#rate_limited"
  }
}

Every response, errors included, has an x-request-id header. Include it when you contact support.

Error codes

These are the codes the /v1 API returns, with their HTTP status:

Rate limits

Requests are limited per minute, per team and per key mode: all live keys of a team share one budget, and all test keys share another. A live key's budget depends on the plan:

• Previews (POST /v1/templates/:id/preview) also have a limit of 30 per minute per team and key mode.
• At the same time, a team can have this many PDFs rendering: Free 1, Starter 2, Growth 3, Pro 4 and Scale 4, across live keys, test keys, previews and the dashboard. One more gets 429 rate_limited with details: { "reason": "concurrency", "limit": N } and Retry-After: 1.
• Per IP address, all requests together (including file downloads and requests with an invalid key) are limited to 600 per minute.

Responses to authenticated requests carry the budget of the limit that applies:

A request over the limit gets 429 with the code rate_limited. Wait for Retry-After seconds, then retry.

Retrying safely

• 429 rate_limited: retry after the Retry-After delay.
• 503 service_busy: retry after a few seconds, with exponential backoff. If the message says storing PDFs is paused, request the PDF directly ("response": "binary") meanwhile.
• 429 storage_limit_reached: the team's stored PDFs are at the plan's limit. Retrying soon gives the same answer; request the PDF directly, or wait for older files to expire (stored PDF limits).
• 500 internal_error: retry once; if it persists, contact support with the x-request-id.
• 409 idempotency_conflict: the first request with this key is still running; retry later with the same key.
• Network errors and timeouts: retry POST /v1/pdf with the same Idempotency-Key. If the first attempt succeeded, you get its document back and nothing is counted twice (idempotency).
• 4xx codes other than 409 and 429 describe a problem with the request, the template or your plan: retrying the same request gives the same answer.

async function createPdf(body, idempotencyKey) {
  for (let attempt = 1; ; attempt++) {
    const res = await fetch('https://api.castpdf.com/v1/pdf', {
      method: 'POST',
      headers: {
        Authorization: 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey,
      },
      body: JSON.stringify(body),
    });
    const retryable = res.status === 429 || res.status === 503;
    if (!retryable || attempt === 5) return res;
    const seconds = Number(res.headers.get('retry-after')) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
  }
}

import time
import requests

def create_pdf(body, idempotency_key):
    for attempt in range(1, 6):
        res = requests.post(
            "https://api.castpdf.com/v1/pdf",
            headers={"Authorization": "Bearer YOUR_API_KEY", "Idempotency-Key": idempotency_key},
            json=body,
            timeout=60,
        )
        if res.status_code not in (429, 503) or attempt == 5:
            return res
        time.sleep(int(res.headers.get("Retry-After", 2 ** attempt)))

Other codes

The dashboard uses the same error format. These codes come only from the dashboard (sign-in, API keys, billing and the Generate PDF button), never from /v1: