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 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, 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 returns a 2xx with success: false, and the global error middleware uses status: false / message rather than success: false / error.

Two 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, or an account pending permanent deletion) returns { "message": "...", "tokenExpired": false }.
• Anything that falls through to the global error middleware returns shape 2 — { "status": false, "message": "...", "errors": [...] } — with no code. Mongoose validation failures, malformed ObjectIds, multipart size-limit rejections and unhandled exceptions all land here, and all of them report 500 unless the thrown error set its own status.

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 emit { "success": false, "error": "...", "code": "API_KEY_READ_ONLY" }. Read error ?? message.

No per-endpoint limiter is applied to GET /models, GET /account/credits, GET /presets, GET /cinematic-presets, GET /voices, GET /projects, GET /project/lightweight, GET/DELETE /visual-dna/{id}, GET /visual-dna, 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 5,000/min global ceiling — poll freely, but cache GET /models rather than calling it per generation.

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. Switching surfaces does not multiply your vendor-spend allowance.

Four different 429 bodies exist on /api/v1 — the global-ceiling shape, the per-endpoint shape, the Color DNA shape, and the project-creation shape. Only two of the four carry a code, the field holding the message differs, and retryAfter is absent from one of them. Detect rate limiting by HTTP status 429, then fall back to retryAfter (or the 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 image_url + operation from the same key within 30 seconds with 409 DUPLICATE_REQUEST, and returns an existingGenerationId you can poll instead.
• The two paid music-library routes (POST /v1/music-library/clean/:trackId, POST /v1/music-library/import) are idempotent through the request id you supply — send a stable 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 10/min 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 10 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).