Every error response is JSON with at least anDocumentation Index
Fetch the complete documentation index at: https://docs.kodisc.com/llms.txt
Use this file to discover all available pages before exploring further.
error field, and often a message for humans:
Status codes
| Status | Meaning | What to do |
|---|---|---|
400 | Request body or parameters invalid (bad className, unknown quality, non-https:// webhookUrl, malformed JSON, …). | Read error; fix the field it names. These are deterministic — don’t retry without changing the request. |
401 | Missing, malformed, revoked, or unknown API key. | Check that Authorization: Bearer kdsc_live_… is set and matches a live key in the dashboard. |
402 | Not enough credits to start the render. | Top up from billing or wait until your monthly free allotment resets. |
404 | The jobId doesn’t exist or doesn’t belong to this key’s user. | Confirm the ID; jobs are scoped to the user that created them. |
5xx | Transient server-side failure. | Retry with exponential backoff. |
200 from GET /api/v2/render/{jobId} — the failure surfaces as status: "failed" with error populated. HTTP 5xx is reserved for Kodisc-side problems, not your scene’s.
The credit model
Credits are the unit Kodisc bills against. Each render consumes credits proportional to its wall-clock render time and quality preset. The lifecycle of credits during a render:Reserve
On
POST /api/v2/render, Kodisc reserves a minimum amount of credits up-front. If your balance is below the reserve, the call fails with 402 immediately — no job is created.Settle
When the render finishes, Kodisc computes the actual cost from
durationMs and quality. If the actual cost exceeds the reserve, the difference is charged. If you don’t have enough to cover it, the job is marked failed and the reserve is refunded.GET /api/v2/me — the response splits paid (purchased credits) from free (your plan’s monthly allowance).
Common 400 messages
error | Cause |
|---|---|
JSON body required | Body wasn’t valid JSON. |
code is required | code was missing or empty. |
className must be a valid Python identifier | className didn’t match ^[A-Za-z_][A-Za-z0-9_]*$. |
quality must be one of: low, medium, high, twok, fourk | Unknown quality. |
aspectRatio must be one of: 16:9, 9:16 | Unknown aspectRatio. |
fps must be a positive integer | fps wasn’t a positive integer. |
webhookUrl must be an https:// URL | webhookUrl was set but didn’t start with https://. |
Retry strategy
400and401are client errors — retrying without changes won’t help.402clears as soon as your balance increases; retry after topping up or after the next free-credit refresh.404is permanent for the givenjobId.5xxand network errors are safe to retry; use exponential backoff (e.g. 1s → 2s → 4s, up to 5 attempts).