Transloadit

Best practices

Get the most out of Transloadit in terms of security, reliability, and performance.

Security

Use Templates

Templates let you store Assembly Instructions on our side, encrypted at rest. You then reference a Template by template_id in your API request. This is safer than sending full instructions on every request, especially if your instructions contain third-party credentials.

Using Templates also improves operability:

  • You can change processing behavior without redeploying your app.
  • You can combine Templates with Assembly Notifications and Assembly Replays.
  • You can still override specific values at runtime when needed.

Learn more:

Sign browser-facing requests

If requests can be generated client-side, assume your auth key may become visible. Use Signature Authentication and HTTPS endpoints (https://api2.transloadit.com).

This protects request integrity and helps prevent unauthorized usage.

Use least-privilege credentials

When granting storage access (for example S3), scope credentials to the minimal required actions and paths. For example, write-only export credentials are often sufficient for 🤖/s3/store.

Reliability

Prefer asynchronous processing

If users have to wait for full processing before continuing, queue time directly impacts UX.

A better pattern:

  1. Upload/import first.
  2. Let processing continue asynchronously.
  3. Use Assembly Notifications to update your backend when the Assembly completes.

This keeps your UI responsive and avoids users waiting on conversions.

Learn more: Webhooks and Notifications

Do not rely on result ordering

Result arrays are not guaranteed to align by position across Steps. If you need to map processed files back to originals, match by IDs:

  • uploads[*].id
  • results[*].original_id

Cap input files per Assembly

Very large input sets in one Assembly can backfire:

  • You can exceed your available priority job slots.
  • You increase the risk of hitting the 8-hour maximum Assembly execution time.

As a practical guideline, keep uploaded and imported input files to around 500 to 1000 files per Assembly, depending on the amount of work each file goes through.

Use ignore_errors intentionally

The ignore_errors Step parameter keeps an Assembly moving when certain per-file errors are acceptable, which is useful for batch jobs or optional metadata extraction. It also makes failures less visible, so apply it deliberately:

  • Prefer targeted arrays like ["meta"] over true, so only the phases you expect to tolerate are ignored.
  • Monitor ignored_errors and ignored_error_count on the Assembly Status so silent failures are still surfaced to your team.

Learn more: The ignore_errors parameter

Read each Robot’s docs

Demos are a great starting point, but production behavior often depends on options, edge cases, and limits documented per Robot.

Before rollout, validate your exact flow against the relevant Robot docs.

Performance & cost

Deliver via Smart CDN

If you deliver processed assets to end users, use the Transloadit Smart CDN.

Key advantages:

  • Lower latency with edge delivery.
  • Better reliability under load.
  • Lower repeated processing and origin traffic via caching.

Best practices:

  • Configure caching behavior on 🤖/file/serve.
  • Prefer URL-based transformations where appropriate.
  • Keep cache keys stable and explicit.

Learn more: Content Delivery

Batch files into fewer Assemblies

Assemblies are heavier than individual file operations. Batching files into fewer Assemblies can improve throughput and reduce overhead, especially for large imports.

For imports, keep total batch size practical for retries and operational safety.

Keep encoding stacks up to date

We keep older stacks available to preserve backwards compatibility, but you should periodically upgrade to newer stacks for fixes, performance improvements, and codec/tooling updates.

Review stack settings at least once per year and test before switching production traffic.

Set a bill limit

While integrating, accidental loops can happen and create unexpected usage spikes. A bill limit is a useful safety guardrail.

Set it high enough to allow normal growth, but low enough to cap unexpected runaway behavior.