DocsDevelopers

Errors and pagination

The error shape, every error code and how lists are returned.

Every failure answers the same JSON shape, so you can branch on error.code and show error.message to people.

The error shape#

Response

{
  "error": {
    "code": "invalid_request",
    "message": "fields needs a storyId",
    "details": [{ "path": "fields", "message": "fields needs a storyId" }],
    "request_id": "req_Xk1E8YGNxZDS"
  }
}

details appears on validation errors, one entry per problem. request_id is also in the X-Request-Id header; quote it when you write to us.

Codes#

Status	Code	Meaning
400	`invalid_request`	The body or a parameter is invalid; see details.
401	`unauthorized`	Missing, unknown, revoked or expired API key.
402	`insufficient_credits`	The workspace needs more credits for this (a render, or generations past the monthly quota).
403	`plan_required`	The plan does not include this (the API, 4K, translations, more brand kits).
403	`forbidden`	The key may not do this.
404	`not_found`	No such object in this key's workspace.
405	`method_not_allowed`	That HTTP method is not supported on this path.
409	`conflict`	The object is not in a state that allows this yet (still generating, archived), or an idempotent request is still running.
413	`payload_too_large`	The body is larger than the endpoint accepts.
422	`idempotency_mismatch`	The Idempotency-Key was already used with a different body.
422	`unprocessable`	The request is well-formed but cannot be done (for example composition code that fails the safety check).
429	`rate_limited`	Too many requests, or the plan's AI limits for now. Wait for Retry-After.
500	`server_error`	Something went wrong on our side. Retry; if it keeps happening, write to us with the request id.
503	`not_configured`	The service is temporarily unavailable.

Pagination#

There is no pagination. List endpoints return everything in one data array: GET /v1/stories every built-in story, GET /v1/brand-kits the workspace's kits (up to 200, default first).

Request size#

Bodies are JSON (Content-Type: application/json) up to 64 KB, or 512 KB for PATCH /v1/videos/:id, which can carry a whole video document.