Errors

One envelope

Every failure — validation, auth, quota, or an unhandled crash — comes back in the same shape:

{
  "statusCode": 403,
  "message": "This API key does not have the renders:write scope.",
  "error": "Forbidden",
  "requestId": "b3f1c2a4",
  "path": "/api/v1/renders"
}

Codes

Branch on code where it exists; it is stable, and message is not.

Statuses

Validation errors name every field

Input failures are enumerated, not reported one at a time, so a fix-and-retry loop converges in one round trip:

{
  "statusCode": 400,
  "message": "Invalid inputs.",
  "errors": [
    { "field": "headline", "message": "Input \"headline\" must be a string." },
    { "field": "hero", "message": "Input \"hero\" must be a public http(s) URL. Host resolves to a private address." },
    { "field": "logo", "message": "Unknown input \"logo\"." }
  ]
}

Unknown input means the key is not declared on the template. Read GET /v1/templates/{id} and compare against inputs[].id.

Publishing and importing name the layer

The refusal a first template most often meets. Media whose source lives only on the author’s machine cannot be fetched by the render service, so a template built on it is rejected rather than rendering the layer as nothing:

{
  "statusCode": 400,
  "code": "unrenderable_assets",
  "message": "Some layers have sources the render service cannot fetch, so they would render empty. Re-host them at a public URL, or expose them as required inputs.",
  "layers": [
    {
      "layer": "Hero Image",
      "reason": "its footage was imported from local storage and was never uploaded, so only this machine can resolve it"
    }
  ]
}

Two fixes, either works: re-host that artwork at a public URL and re-import, or expose the layer as a required input so your workflow supplies a URL on every render. Import does the second automatically — which is why an imported project rarely sees this, and a hand-authored one sometimes does.

Upload errors

POST /v1/assets refuses early rather than storing something the renderer will choke on later:

A generic application/octet-stream is not a contradiction — it reads as “no type given”, and the bytes decide. That is what most HTTP clients send.

What errors never contain

Server-side messages are sanitised before they reach you. A database failure answers a generic 500 — the underlying query, table and column names stay in the server log, keyed by the requestId you were given. If a 500 is reproducible, quote that id.

A retry policy that works

async function call(url, init, attempt = 0) {
  const res = await fetch(url, init)
  if (res.ok) return res.json()
 
  const body = await res.json().catch(() => ({}))
 
  // Retryable: rate limit and server-side failure. Nothing else.
  const retryable = res.status === 429 || res.status >= 500
  if (!retryable || attempt >= 4) {
    throw new Error(`${res.status} ${body.code ?? ''} ${body.message ?? ''} (${body.requestId})`)
  }
 
  const wait = body.retryAfterSeconds
    ? body.retryAfterSeconds * 1000
    : 2 ** attempt * 1000
  await new Promise((r) => setTimeout(r, wait))
  return call(url, init, attempt + 1)
}