Errors - Framelane

Error shape

All API errors follow this JSON envelope:

{
  "error": {
    "code": "not_found",
    "message": "Render not found.",
    "details": {}
  }
}

Field	Type	Description
`code`	string	Machine-readable error code (see table below)
`message`	string	Human-readable description
`details`	object	Optional additional context

Validation errors

When a request fails schema validation (code: "invalid_request", HTTP 422), details.errors lists each problem. Unknown fields are rejected, not silently ignored — a typo like font_wight fails loudly instead of being dropped, so an edit never appears to succeed while changing nothing.

{
  "error": {
    "code": "invalid_request",
    "message": "Request validation failed.",
    "details": {
      "errors": [
        {
          "type": "extra_forbidden",
          "loc": ["body", "elements", 0, "text", "font_wight"],
          "msg": "Extra inputs are not permitted",
          "pointer": "/elements/0/font_wight",
          "suggestion": "font_weight"
        }
      ]
    }
  }
}

Field	Type	Description
`type`	string	Machine-readable failure kind (`extra_forbidden`, `enum`, `missing`, …).
`loc`	array	pydantic location path (includes the union-variant tag for element errors).
`msg`	string	Human-readable explanation.
`pointer`	string	RFC 6901 JSON pointer to the offending value, e.g. `/elements/0/font_wight`.
`suggestion`	string	Present when a close valid field name or enum value exists — “did you mean `font_weight`?”. Advisory.

suggestion is omitted when there is no close match, and for a misplaced real field (e.g. duration on a video element — use out_point for clip length), where a fuzzy guess would mislead. Structurally-impossible project ops (POST /v1/projects/{id}/ops) also carry a pointer in details, e.g. /ops/0.

HTTP status codes

Status	Meaning
`200`	OK
`202`	Accepted — job enqueued
`201`	Created
`204`	No content
`400`	Bad request
`401`	Unauthorized — invalid or missing API key
`402`	Payment required — free-plan render-time cap exhausted
`403`	Forbidden
`404`	Not found
`409`	Conflict — `conflict` (Idempotency-Key reused with a different body) or `email_in_use` (a signup for this email is already in progress)
`422`	Unprocessable entity — validation failed
`429`	Too many requests — rate limit exceeded
`500`	Internal server error
`503`	Service unavailable: a dependency, such as the shader compiler, is not available

Error codes

Code	HTTP	Description
`unauthorized`	401	Missing or invalid API key
`forbidden`	403	Action not permitted for this workspace
`not_found`	404	Resource does not exist
`conflict`	409	Idempotency key conflict
`invalid_request`	422	Request validation failed
`unsupported_feature`	422	Feature not yet supported
`invalid_source`	422	Source URL is invalid or inaccessible
`source_not_found`	422	Source URL returned 404
`source_too_large`	422	Source file exceeds the 5 GiB limit
`asset_not_ready`	422	Referenced media is still being processed (retry after the `asset.ready` webhook)
`ingest_failed`	—	A public video/audio file could not be probed for its duration: unreachable, not a direct media URL, or the probe timed out (set on the failed job)
`codec_unsupported`	422	Codec not supported by the render engine
`quota_exceeded`	402	Monthly free-plan render-time cap exhausted. `details` carries `limit_seconds`, `used_seconds`, `requested_seconds`. Not retryable — upgrade or wait for the monthly reset
`rate_limited`	429	Too many requests in the current window
`email_not_verified`	403	Workspace email not verified — call `POST /v1/signup/verify` with the emailed OTP. Returned on every authenticated call until then
`email_in_use`	409	A signup for this email is already in progress; retry
`invalid_otp`	400	Verification code incorrect or expired (15-minute TTL, 5 attempts)
`unsupported_content_type`	422	`content_type` not in the allowed upload list; `details.allowed` lists them
`plan_required`	402	The feature needs a higher plan; `details.required_plan` names it
`admin_only`	403	Only an admin workspace may write the template catalogue
`template_assets_not_shared`	422	A published template may use only shared CDN media; `details.urls` lists the rest
`template_has_webhook`	422	A published template may not carry a `webhook_url`, since every copy of it would notify that URL
`shader_compile_error`	422	A shader’s SkSL did not compile (`POST /v1/shaders`): `details.errors` lists each as `{line, col, message}` and `details.shader_id` names the stored, failed shader. At a render: an effect names a shader that failed to compile
`shader_compiler_unavailable`	503	The shader compiler is not installed on this deployment, or did not answer within its timeout
`shader_not_found`	422	An effect’s `shader.id` is neither one of this workspace’s shaders nor a shared one
`shader_param_invalid`	422	An effect’s `shader.params` sets a param the shader does not declare, or a value of the wrong type or outside its declared range
`render_refused`	—	The renderer refused the composition by name: a runtime shader that did not compile or ran over its GPU time budget, or an operation, a component or a nested composition it could not apply. `message` carries the renderer’s words; change what it names (set on the failed job)
`http_error`	—	Generic HTTP error not covered by a more specific code
`internal`	500	Unexpected internal error

Job-level errors

When a render or task fails asynchronously, the error field is set on the job object:

{
  "id": "render_01J...",
  "status": "failed",
  "error": {
    "code": "source_not_found",
    "message": "Source URL returned 404: https://cdn.example.com/missing.mp4"
  }
}

The same error is included in the render.failed / task.failed webhook payload.