Production best practices

Bound work and memory

Use a bounded queue for media work. Rate limits, processing concurrency and account quotas are separate controls. Inspect your effective limits in the Customer portal; a public pricing template is not your assigned limit snapshot.

SDKs buffer media uploads/responses. HTTP clients and multipart construction can require additional memory; base64 PDF pages are larger than raw bytes. Bound source sizes, output sizes, page counts and simultaneous requests. Use a direct HTTP implementation if you require a different streaming strategy.

Choose explicit request deadlines. Current SDK defaults are 30 seconds for light operations, 60 seconds for images and 120 seconds for PDF calls. A client timeout does not extend the backend worker’s own deadline or guarantee cancellation of server work.

Retry only when replay is safe

The SDKs do not automatically retry mutations. Use bounded exponential backoff with jitter for temporary rate/capacity failures, honoring Retry-After when present. Treat validation, authentication and exhausted entitlements as conditions to fix.

A lost POST response can leave a completed, chargeable operation or stored resource. This contract does not promise a general idempotency-key mechanism. Record returned IDs and reconcile resource lists/state when possible; do not blindly repeat upload, transform, generation or artifact-save requests.

For reads, retry within a deadline and concurrency budget. A 304 means reuse your cached bytes, not read a new body.

Choose retention and caching deliberately

Upload an original once for reusable variants. CACHE and PERSIST retain derivatives according to their mode rules; EPHEMERAL does not provide later derivative retrieval. Code/PDF generation is transient unless saved separately.

Keep ETags for conditional derivative downloads. A valid derivative 304 consumes no output bandwidth. Stored cache hits avoid repeated transformation processing, but output bandwidth still counts. Remote fetches incur their additional credit even before a remote cache hit.

Expired cache entries stop being served before physical cleanup releases storage. Deletion refunds stored bytes, not past credits or bandwidth. Track original and output IDs, and delete only resources your retention policy says are no longer needed.

Observe and validate the deployment

Record sanitized request IDs, status, duration, operation and output byte counts. Monitor quota pressure, timeouts and capacity errors. Keep application logs free of keys and private media.

1. Verify configured API origin, project context and assigned entitlements.
2. Test a small upload, binary output, multi-page PDF JSON and a deliberate validation failure.
3. Test authorization on your own delivery endpoints and revoke a test key.
4. Verify cleanup, retention and response handling using synthetic media.

Use the downloadable development contract for validation tooling. Deployment compatibility, registry publication and owner release gates still require separate release checks.