Errors & Rate Limits

Never key your error handling on success alone, and never assume code is present. Branch on the HTTP status first, then read error ?? message, then treat code as optional. A client that only checks data.success === false will silently treat every shape-2 and shape-3 error as a success.

Even within shape 1, code is not guaranteed — several SDK validation errors return only { "success": false, "error": "..." } (for example Provide video_url or upload a video file on video-to-video, image_url is required on image-to-video, Generation not found on status and cancel, or source and id are required on the stock routes).

Do not test for an exact success status either. 200, 201 and 202 are all in use on the submit call depending on the endpoint (see the table below), so status === 200 rejects working jobs. The check that holds across every route is response.ok and neither failure flag set:

if (!res.ok || body.success === false || body.status === false) {
  throw new Error(body.error ?? body.message ?? `HTTP ${res.status}`);
}

Both flags are needed: TRACKING_ERROR can return a 2xx with success: false, and shapes 2 and 3 use status: false / message rather than success: false / error.

Some responses on /api/v1 carry no code at all. Detect them by HTTP status.

• 401 from the API-key middleware (bad prefix, unknown / revoked / expired key, a restricted account, or an account pending permanent deletion) returns { "message": "...", "tokenExpired": false }.
• 403 for an unverified email returns { "status": false, "message": "...", "emailNotVerified": true }.
• Shape 3 (malformed or oversized JSON) never carries a code.

403 API_KEY_READ_ONLY also arrives in two different shapes depending on where it was raised: the auth middleware emits { "status": false, "message": "...", "code": "API_KEY_READ_ONLY" }, while the two paid music routes and the project-transfer routes emit { "success": false, "error": "...", "code": "API_KEY_READ_ONLY" }. Read error ?? message. The auth middleware only enforces read-only on keys created with scope enforcement — older keys are grandfathered — but the paid music and project-transfer routes reject any key without write.

A model identifier that is a string but is not in the catalog is rejected. The SDK layer first maps registered aliases and provider-prefixed forms to the canonical identifier; anything still unknown fails before the job starts:

• Image, image edit, video, image-to-video, elements, first-last-frame, lipsync, chat, music, speech, sound, 3D: 400 MODEL_NOT_FOUND, with near-match suggestions in the message.
• Video-to-video: the unknown identifier is passed through, and the controller's error is relayed (falling back to GENERATION_ERROR).

Omitting model, sending a blank string, or an auto alias (auto, smart-select, Smart Select, default, …) still auto-selects. If the server cannot load the catalog to check the identifier (an outage), it runs the default instead of returning 400, so compare the model in the submit response with the one you sent.

No per-endpoint limiter is applied to GET /models, GET /account/credits, GET /account/plans, GET /presets, GET /cinematic-presets, GET /voices, GET /projects, GET /projects/{id}, GET /project/lightweight, GET /project-transfers, GET/DELETE /visual-dna/{id}, GET /visual-dna, POST /generate/music/composition-plan, the project update / archive / context / profile routes, or status polling (GET /generate/{id}/status, GET /generate/creative-director/{id}/status). Those are bounded only by the global ceiling — poll freely, but cache GET /models rather than calling it per generation.

Rejected requests do not spend the per-endpoint buckets. Those limiters skip any request that ends in an error status, so a 400 or a 429 retry does not burn the window it was rejected by. The exceptions, which count every request, are the global ceiling and the project-creation, color-palette analysis, flows, trends and morphious-styles limiters.

The music "paid" bucket is shared with the web app — the same counter backs both surfaces, so cleaning or importing tracks inside app.kolbo.ai consumes the same 5/min the API sees.

At least five different 429 bodies exist on /api/v1 — the global-ceiling shape, the per-endpoint shape, the Color DNA shape, the project-creation shape, and plain text. Only two carry a code, the field holding the message differs, retryAfter is absent from two of them, and one is not JSON. Detect rate limiting by HTTP status 429, then fall back to retryAfter (or the Retry-After / RateLimit-Reset header) for the backoff.

Generation endpoints have no idempotency key. There is no Idempotency-Key header and no client-supplied request id on any /v1/generate/*, /v1/edit/*, /v1/chat or /v1/transcribe call, so re-POSTing the same body creates a second, separately billed job. Only two protections exist anywhere in the API, and neither is general:

• POST /v1/edit/image rejects the same operation on the same image_url from the same account and session within 30 seconds with 409 DUPLICATE_REQUEST. The check is best-effort (it is held in memory on the server that took the first request), and the SDK response does not include the id of the job already running — find it with the reconciliation steps below.
• The two paid music-library routes (POST /v1/music-library/clean/:trackId, POST /v1/music-library/import) are idempotent through the requestId you supply — send the same one when retrying those.

Everything else will happily run twice.

No cap on simultaneously running generations is published. The limits in the table above are request-rate limits (requests per 60-second window), not in-flight-job limits: clearing the 30/min generation bucket says nothing about how many of those jobs may be running at once.

Bound your own fan-out instead. In practice the per-minute limit is the effective ceiling — at 30 starts/min against jobs that run for minutes, a naive batch loop hits 429 long before anything else. Queue work behind the per-endpoint limit, back off on 429 using retryAfter or the RateLimit-Reset header, and remember every key on one account shares the same per-endpoint counters (only the 5,000/min global ceiling is per key).