Skip to main content

​
Authentication

  • API key is stored in a secret manager, not in source code
  • Key rotation procedure is documented and tested
  • Old keys are revoked after rotation

​
Idempotency

  • Every POST /v1/renders and POST /v1/tasks/* call includes an Idempotency-Key header
  • Idempotency keys are unique per logical operation (e.g. UUID tied to your internal job ID)
  • Retry logic checks for 200 (replay) vs 202 (new job)

​
Webhooks

  • Webhook endpoint is HTTPS with a valid certificate
  • HMAC signature verification is implemented (see Signature Verification)
  • Webhook handler returns 200 within 10 seconds to avoid retry storms
  • Dead-letter events are monitored and alerted on

​
Validation

  • Compositions are validated with POST /v1/preview {"dry_run": true} before submitting — it is free, unmetered, and runs the same strict translator the submit path uses, so ok: true means the render will be accepted
  • violations[] entries with severity: "error" in that dry-run response block the submit in your pipeline; warning findings are logged and reviewed
  • The ok / violations[] that come back on a 202 from POST /v1/renders, POST /v1/projects/{id}/renders and a 201 from POST /v1/projects are advisory: that render is already queued and billable. They are your safety net, not your gate — the gate is the free dry-run above. Alert on ok: false there rather than assuming the submit was refused

​
Error handling

  • 429 responses are retried with exponential backoff
  • 402 quota_exceeded is handled distinctly from 429 — it is a monthly render-time cap, not a rate limit, and must not be retried with backoff
  • failed job status triggers your own alerting
  • source_not_found / invalid_source errors surface meaningful messages to your users

​
Observability

  • All Framelane job IDs are logged alongside your internal IDs
  • Webhook delivery failures are tracked
  • Monthly quota usage is monitored (alert before hitting limits)

​
Source URLs

  • All source_url values are publicly accessible HTTPS URLs
  • Source files are under 5 GiB
  • Source URLs remain valid for at least 1 hour after job submission (the render engine fetches them asynchronously)