Errors

Error response shape

Every Generate endpoint (/generate-and-post, /jobs, /blog-to-video, /videos/magic, /videos/text-to-video, /videos/image-to-video, /videos/ai-influencer, /clipper/youtube, /avatars, /batch) answers every error in this one envelope:

{
  "success": false,
  "error": {
    "code": "INPUT_INVALID",
    "message": "prompt: Prompt must be 1000 characters or less",
    "retryable": false,
    "details": { ... }          // optional, code-specific
  },
  "meta": { "request_id": "8f0c…" }
}

• error.code — stable identifier. Branch on this.
• error.message — human-readable explanation for developers.
• error.retryable — whether retrying the same request later can succeed. Always a boolean.
• error.details — optional, code-specific context (for validation errors, the failing fields). Some codes also put extra fields directly on error (for example the 402 cost_usd_cents and balance_usd_cents).
• meta.request_id — the same value as the X-Request-Id response header. Include it when contacting support.

Validation errors are always 400 INPUT_INVALID and are never charged: an invalid AI video request (for example a prompt over 1,000 characters or an unsupported resolution) is rejected before billing. Older responses also carried a top-level message; it is kept as a deprecated alias of error.message.

Other routes. A few older pass-through routes outside Generate (for example schedules) can still return { "success": false, "message": "...", "error": "<text>" } where error is a string. Clients that call those should check whether error is an object and fall back to message when it is not.

Dry runs: check a request before paying

Send "dry_run": true in the body of any Generate endpoint. The request goes through the same validation and normalization as a real call, and you get the price back. Nothing is queued, nothing is charged and no Idempotency-Key is needed. Invalid input returns the same 400 a real call would.

curl -X POST https://api.reelsbuilder.ai/api/v1/videos/text-to-video   -H "Authorization: Bearer $REELSBUILDER_API_KEY"   -H "Content-Type: application/json"   -d '{ "prompt": "A lighthouse at dawn", "quality_tier": "medium", "duration_sec": 30, "dry_run": true }'

# -> 200
{
  "success": true,
  "data": {
    "dry_run": true,
    "valid": true,
    "mode": "text_to_video",
    "normalized_request": { "model": "kling-3.0-standard", "prompt": "A lighthouse at dawn", "options": { "duration": 30, "native_audio": false, "music": true, ... } },
    "price": {
      "usd_cents": 430,
      "display": "$4.30",
      "breakdown": [{ "item": "generate_ai_video", "usd_cents": 430, "model": "kling-3.0-standard", "tier": "medium", "duration_sec": 30, "narrated": false }]
    },
    "estimated_duration_sec": 30,
    "estimated_render_seconds": { "min": 180, "max": 900 },
    "warnings": [],
    "charged": false
  },
  "meta": { "request_id": "…" }
}

• price.usd_cents is exactly what the real call would charge (the same pricing function bills it).
• warnings lists things worth fixing, such as an alias that has a canonical name.
• estimated_render_seconds is a typical range, not a guarantee.
• /batch accepts a top-level dry_run and returns each item's result plus the total price.
• Sending dry_run to a paid endpoint that does not support it (for example /post) returns 400 DRY_RUN_NOT_SUPPORTED instead of running for real.

Error code reference

Failed jobs report their own error in data.job.error (code, message, retryable) on GET /api/v1/jobs/{id}; plan tokens and API credits for failed jobs are refunded.

Retry decision tree

1. 2xx → success.
2. 400, 401, 402, 422 → fix the request (or top up), then send it with a new Idempotency-Key. Error responses are cached against the old key for 24 hours — see Idempotency.
3. 409 RESOURCE_ALREADY_EXISTS → you reused a key for a different request. Generate a new key.
4. 429 → wait for Retry-After (rate limit) or for an active render to finish (concurrency). See rate limits.
5. 5xx → retry with exponential backoff (for example 1s, 2s, 4s, 8s, capped at 60s).
6. 501 → the endpoint is not live yet; don't retry.

Handler pattern (TypeScript)

type ApiErrorBody = {
  success: false;
  message?: string; // deprecated alias of error.message
  error?: { code: string; message: string; retryable: boolean; details?: unknown } | string;
  meta?: { request_id?: string };
};

function describeError(status: number, body: ApiErrorBody) {
  if (body.error && typeof body.error === "object") {
    return { status, code: body.error.code, message: body.error.message, retryable: body.error.retryable };
  }
  // Older non-Generate routes only: error is a string (or missing)
  return { status, code: "UNKNOWN", message: body.message ?? String(body.error ?? ""), retryable: status >= 500 };
}

const res = await fetch(url, init);
if (!res.ok) {
  const err = describeError(res.status, await res.json());
  switch (err.code) {
    case "INSUFFICIENT_API_CREDITS":
      throw new Error("Top up API credits, then retry with a new Idempotency-Key");
    case "AUTH_REQUIRED":
    case "AUTH_INVALID_API_KEY":
      throw new Error("Check the API key");
    case "RATE_LIMIT_EXCEEDED":
    case "RENDER_CONCURRENCY_LIMIT_EXCEEDED":
      throw new Error("Back off and retry later");
    default:
      throw new Error(`${err.code}: ${err.message} (request ${res.headers.get("x-request-id")})`);
  }
}

Unknown codes

New codes may be added. Give your handler a default branch that logs unfamiliar codes and uses retryable rather than crashing.

Reporting an issue

Email admin@reelsbuilder.ai with:

• The X-Request-Id header from the failing response
• The error.code and approximate timestamp (UTC)
• What you were trying to accomplish

See also

• Authentication errors
• Rate limits + 429 handling
• Idempotency replay vs conflict