Errors
How the Rodin API reports failures, and what every error code means.
How errors are returned
The Rodin API reports failures in two different places, and a correct client checks both.
Transport-level failures use the HTTP status: 400 for a malformed request, 401 for missing or invalid authentication, and 429 for throttling.
Application-level failures use the response body, not the HTTP status. A rejected submission is still returned as HTTP 201, with the reason in error and human-readable detail in message. A client that only inspects the HTTP status will treat a rejection as a successful submission and then poll an identifier that was never created.
{
"error": "API_INSUFFICIENT_FUNDS",
"message": "The fund in your wallet is insufficient to perform this operation."
}Submission errors
Returned by Rodin Gen-2.5, Rodin Gen-2, Rodin Gen-1/1.5, Generate Texture, and Bang.
| Code | Meaning |
|---|---|
INVALID_REQUEST | Malformed request, missing parameters, or invalid values. See message. |
API_NO_ACTIVE_SUBSCRIPTION | The account has no active subscription. |
API_SUBSCRIPTION_PLAN_TOO_LOW | The subscription plan does not allow API access. |
API_PARALLELISM_LIMIT_REACHED | Too many of the account's tasks are already running. Retry once one finishes. |
API_INSUFFICIENT_FUNDS | The account balance is too low for this request. |
API_OBJECT_NOT_FOUND_ON_IMAGE | No object was detected in the input image, or the image is unsupported. |
IMAGE_CONTENT_VIOLATION | The input image is not allowed in your region. Try another image. |
IMAGE_LABEL_LENGTH_TOO_LONG | More image_label entries were sent than uploaded images. |
NO_SUCH_TASK | The referenced task does not exist or has expired. |
ASSET_NOT_AVAILABLE | The referenced asset is not in a state that can be operated on. |
PERMISSION_DENIED | The account may not perform this action. |
API_UNKNOWN | Unexpected server-side error. See message. |
Text-to-3D prompts are rendered to an image before generation, so a prompt-only request can also return IMAGE_CONTENT_VIOLATION.
Status and download errors
Check Status can return:
| Code | Meaning |
|---|---|
NO_SUCH_TASK | The subscription key does not identify an available task. |
Download Results can return:
| Code | Meaning |
|---|---|
NO_SUCH_TASK | The task UUID does not identify a task owned by this user. |
INVALID_REQUEST | The task has no downloadable files for this user. |
A common mistake is sending the wrong identifier: /status takes jobs.subscription_key and /download takes the top-level uuid. Swapping them returns NO_SUCH_TASK.
Throttling and retries
Rate limits are applied per endpoint and per account, and the limit for polling /status is far higher than for submitting generations. The official pricing page publishes a per-minute figure for Business API access, but it varies by subscription tier and can change, so do not hard-code it.
HTTP 429 carries a Retry-After header giving the number of seconds to wait. Honor it rather than retrying immediately, and treat the header as authoritative over any published rate figure.
Retry 429 and 5xx responses with backoff. Do not retry a body-level error: those are deterministic rejections, and resubmitting produces the same result while consuming another request against your rate limit.