API error codes reference

Every error response uses the same shape:

{ "error": { "code": "ERROR_CODE", "message": "Human-readable description" } }

Check the HTTP status and error.code before reading data.

Codes

Code	HTTP	What to do
`UNAUTHORIZED`	401	Missing or invalid auth. Check the `Authorization` header
`FORBIDDEN`	403	Authenticated but not allowed for this resource
`VALIDATION_ERROR`	400	Body failed schema validation. `details.path` points at the field
`INVALID_JOB_TYPE`	400	Job type not registered or not on your plan
`FEATURE_NOT_ENABLED`	400	A compose job uses animated text or 3D turns, which are still rolling out and not enabled for your account yet. Render without them, or contact support to get access
`INSUFFICIENT_CREDITS`	402	Top up at app.rendobar.com/billing
`PLAN_LIMIT`	403	Plan limit hit (job timeout, GPU, a compose frame or frame rate above the plan). See Limits and which plan lifts it
`RATE_LIMITED`	429	Back off per `Retry-After` header
`NOT_FOUND`	404	Resource doesn’t exist or isn’t visible to your org
`CONFLICT`	409	Request conflicts with current state (e.g. cancelling a complete job)
`RUNNER_ERROR`	502	Processing failed on the runner. Check `error.message` for details
`RUNNER_TIMEOUT`	504	A runner accepted the job but never started it, or lost the run. No credits charged
`ORG_SUSPENDED`	403	Contact `hello@rendobar.com`
`INTERNAL_ERROR`	500	Server bug. Persist? Contact support with the request ID
`STORAGE_QUOTA_EXCEEDED`	402	Stored assets exceed the plan quota. Delete assets or upgrade
`FILE_TOO_LARGE`	413	Input is larger than the plan allows. Check `maxInputFileSize` on /account/capabilities
`QUEUE_FULL`	429	Too many jobs already waiting. Let some finish, then retry
`QUEUE_EXPIRED`	400	The job waited too long to be dispatched. Submit it again
`GONE`	410	The output has passed its retention window and was deleted
`INPUT_URL_BLOCKED`	400	The input URL is not fetchable. Private and link-local addresses are refused
`INPUT_FETCH_FAILED`	400	The input URL could not be downloaded. Check it is public and still there
`INPUT_NOT_MEDIA`	422	The input downloaded but is not media
`INPUT_UNSUPPORTED`	422	The input is media of a kind this job type cannot take
`PROCESSING_FAILED`	422	The input was readable but the job could not produce an output
`UPSTREAM_ERROR`	502	A third-party service the job depends on failed. Retry
`NOT_CONFIGURED`	503	The capability is not configured on this deployment. Contact support
`NOT_IMPLEMENTED`	501	The endpoint exists but does nothing yet

Which plan lifts a PLAN_LIMIT?

A compose video above your plan and a GPU job on Free return PLAN_LIMIT with error.details, a list of problems shaped { path, message, upgradeTo }. upgradeTo is "pro" or "studio", the cheapest plan that runs the job. It is null when only an enterprise plan does. Read upgradeTo instead of parsing the message.

{
  "error": {
    "code": "PLAN_LIMIT",
    "message": "A 3840x2160 video at 30 fps is above your plan, which renders compose up to 1080p at 30 fps. Studio ($29/month) renders it.",
    "details": [
      { "path": ["output"], "message": "A 3840x2160 video at 30 fps is above your plan, which renders compose up to 1080p at 30 fps. Studio ($29/month) renders it.", "upgradeTo": "studio" }
    ]
  }
}

Storage connections

Creating, testing, or updating a storage connection returns these codes:

Code	When
`VALIDATION_ERROR`	An access check failed, or the change is not allowed, such as making a read-only connection the default destination. `details.field` names the field to fix, and `details.reason` gives the cause, such as `bucket_not_found` or `signature_mismatch`
`CONFLICT`	The connection id is taken, or you deleted a connection that still has deliveries in progress
`UPSTREAM_ERROR`	The storage provider did not respond, or failed while listing objects. Retry
`NOT_CONFIGURED`	Sign in with Supabase is not available. Connect with S3 access keys instead

A failed delivery does not return an error code. The job reports a reason for that destination instead. See delivery errors.

How do I handle the common errors?

The three you’ll hit most: INSUFFICIENT_CREDITS, RATE_LIMITED, VALIDATION_ERROR.

import { createClient, isApiError } from "@rendobar/sdk";

const client = createClient({ apiKey: "rb_YOUR_KEY" });

try {
  const job = await client.jobs.create({
    type: "ffmpeg",
    params: { command: "ffmpeg -i https://example.com/video.mp4 -vf scale=1280:720 output.mp4" },
  });
} catch (err) {
  if (!isApiError(err)) throw err;
  switch (err.code) {
    case "INSUFFICIENT_CREDITS":
      // redirect to billing
      break;
    case "RATE_LIMITED":
      // back off for err.retryAfter seconds
      break;
    case "VALIDATION_ERROR":
      // fix the request
      break;
    default:
      console.error(`API error: ${err.code} - ${err.message}`);
  }
}

const res = await fetch("https://api.rendobar.com/jobs", {
  method: "POST",
  headers: {
    "Authorization": "Bearer rb_YOUR_KEY",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    type: "ffmpeg",
    params: { command: "ffmpeg -i https://example.com/video.mp4 -vf scale=1280:720 output.mp4" },
  }),
});

if (!res.ok) {
  const { error } = await res.json();
  switch (error.code) {
    case "INSUFFICIENT_CREDITS":
      // redirect to billing
      break;
    case "RATE_LIMITED":
      // back off per Retry-After
      break;
    case "VALIDATION_ERROR":
      // fix the body
      break;
    default:
      console.error(`API error: ${error.code} - ${error.message}`);
  }
}

import requests
res = requests.post(
    "https://api.rendobar.com/jobs",
    headers={"Authorization": "Bearer rb_YOUR_KEY"},
    json={
        "type": "ffmpeg",
        "params": {"command": "ffmpeg -i https://example.com/video.mp4 -vf scale=1280:720 output.mp4"},
    },
)
if not res.ok:
    error = res.json()["error"]
    print(f"API error: {error['code']} - {error['message']}")

Getting Started

Concepts

Storage

Jobs

Automation

Developer tools

Support

API error codes reference

Codes

Which plan lifts a PLAN_LIMIT?

Storage connections

How do I handle the common errors?

See also

​Codes

​Which plan lifts a PLAN_LIMIT?

​Storage connections

​How do I handle the common errors?

​See also

​Related

Codes

Which plan lifts a PLAN_LIMIT?

Storage connections

How do I handle the common errors?

See also

Related