Guides / Going to production

Going to production

A short checklist for moving from "it works on my machine" to a dependable integration.

Manage keys safely

Keep keys server-side only, in a secret manager or environment variable. Never ship one in client code or commit it.
Use a separate key per environment (production, staging, CI). You can revoke one without touching the others.
Rotate without downtime: create the new key, deploy it, then revoke the old one. See Authentication.

Handle errors deterministically

Branch on the error code, not the HTTP status, since two errors can share a status. The full list and per-code advice is in Errors. The short version:

Fix and do not retry request errors: invalid_json, invalid_data, template_not_found, template_not_published.
Back off and retry transient ones: rate_limited (honor Retry-After), service_unavailable, and usually internal_error.
Resolve account state for unauthorized and payment_required.

Because a failed call never produces a document or consumes quota, retries are safe; just guard against double-submits on user-triggered generation. See Rate limits & quotas.

Monitor from the dashboard

Three views show what your integration is doing:

Usage — generations used vs. your monthly limit, with a few months of history. Watch this to size your plan.
Metrics — totals, success/error rate, your top templates, and recurring errors grouped by pattern, so a systemic problem (a template that frequently misses a variable) stands out.
History — every generation with its status, the template version that served it, the render duration, and an actionable message on failures.

See Usage, history & metrics for the details and retention windows.

Publish a version and integrate against it knowing it will not change under you. When you need to change a template, edit the draft, preview, and publish a new version deliberately. Roll back if a change misbehaves.

Lock down fidelity

For documents that must look identical every time, remove external dependencies from the render: inline your CSS and embed fonts and images as data: URIs, so nothing is fetched at render time. See Fonts & images.

Choose the right plan

Plans differ on monthly volume, request throughput, active API keys, and history retention. Pick based on your expected volume and burstiness, and remember that throughput (requests per minute) matters as much as the monthly total for spiky workloads. See Plans & limits.

Where the API lives

Generation runs at the /v1/generate endpoint on the API origin. Keep the base URL in configuration rather than hard-coding it, so you can point at a different environment without a code change.