Errors

Error response shape

{
  "success": false,
  "error": {
    "code": "INPUT_INVALID_FORMAT",
    "message": "Field 'platforms' must be a non-empty array of strings.",
    "details": {
      "field": "platforms",
      "received": null,
      "expected": "string[]"
    }
  },
  "meta": {
    "request_id": "req_01HKZ2Q9YX..."
  }
}

• code — Stable identifier. Branch your error handling on this, not on message or status code.
• message — Human-readable. Safe to surface to logged-in developers; do not show to end users without translation.
• details — Code-specific structured info. Empty object if the code has no extra context.
• meta.request_id — Always include this when contacting support — we can trace any request from this ID.

Error code reference

Retry decision tree

1. Status 2xx → success. success: true in body.
2. Status 4xx, code starts with AUTH_, INPUT_, CREDIT_, or RESOURCE_NOT_FOUND → fix the request, then retry. Do not retry blindly.
3. Status 409 RESOURCE_ALREADY_EXISTS → idempotency key collision. Generate a fresh UUID, retry.
4. Status 429 → respect Retry-After. See rate limits.
5. Status 5xx → retry with exponential backoff (recommended: 1s, 2s, 4s, 8s, 16s, cap at 60s). Use the same Idempotency-Key across retries so credits aren't double-charged.

Handler pattern (TypeScript)

type ApiError = {
  success: false;
  error: { code: string; message: string; details?: Record<string, unknown> };
  meta: { request_id: string };
};

async function callApi<T>(url: string, body: unknown, idempotencyKey: string): Promise<T> {
  const res = await fetch(url, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.REELSBUILDER_API_KEY}`,
      "Content-Type": "application/json",
      "Idempotency-Key": idempotencyKey,
    },
    body: JSON.stringify(body),
  });
  const json = await res.json();
  if (!res.ok) {
    const err = json as ApiError;
    switch (err.error.code) {
      case "CREDIT_INSUFFICIENT":
        throw new Error("Out of credits — prompt user to upgrade");
      case "AUTH_INVALID_KEY":
      case "AUTH_FORBIDDEN":
        throw new Error("Auth misconfigured");
      case "AUTH_RATE_LIMITED":
        // caller should respect Retry-After
        throw new Error("Rate limited");
      case "RESOURCE_ALREADY_EXISTS":
        throw new Error("Idempotency collision — regenerate key");
      default:
        throw new Error(`${err.error.code}: ${err.error.message} (req ${err.meta.request_id})`);
    }
  }
  return json as T;
}

Versioning

New error codes can be added in any minor release. Existing codes are never renamed or repurposed. If a code's meaning must change, a new code is added and the old one is deprecated (returned for at least 12 months alongside the replacement).

Build your error handling with a default branch that logs unfamiliar codes rather than crashing.

Reporting an issue

Email admin@reelsbuilder.ai with:

• The meta.request_id 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