Errors
Every refusal code, its HTTP status, whether to retry, and what to do.
Read as MarkdownYour call was refused. Find its code below and do what the row says.
The error body
Same object on REST, MCP and the CLI.
{
"error": {
"ok": false,
"code": "not_found",
"message": "No such generation. Check the generation_id the call that started it returned.",
"retryable": false,
"credits_charged": 0
}
}| Field | Type | What it is |
|---|---|---|
ok | false | Always false on a refusal. |
code | string | One of the 25 codes below. Branch on it. |
message | string | One safe sentence. Show it, never parse it: the wording can change. |
retryable | boolean | May you send the identical request again. |
credits_charged | number | What this refused call cost. Almost always 0. |
Some codes add fields. A field that is not set is left out, never null.
| Field | On | Use |
|---|---|---|
retry_after_seconds | rate_limited, transient request_blocked, submission_in_flight (race) | Seconds to wait. |
in_flight | submission_in_flight (one per key) | generation_id and status of the job already running. Wait on it. |
blocked_reason | request_blocked | The code that got this request blocked. |
capability_status | capability_unavailable, required_plan | coming_soon, retired, requires_plan or unknown. |
required_plan | required_plan | The plan that unlocks it, when known. |
shortfall | insufficient_credits | Credits missing. |
limit | max_credits_exceeded, spend_limit_exceeded | Which cap refused, in limit.bound_by. Spend limits. |
connect_url | connection_not_configured (MCP only) | Page where a person picks the workspace. |
Where it arrives
| Surface | Shape |
|---|---|
| REST | Under error, with the HTTP status from the table. A 429 with retry_after_seconds also sends Retry-After. |
| MCP | The whole object (no error wrapper) as JSON in one text block, with isError: true. |
| CLI | Sentence and code on stderr. --json prints the same object, under error, on stdout. Exit codes: Commands. |
All codes
| Code | HTTP | Retryable | What to do |
|---|---|---|---|
not_authorized | 401 | no | Key missing, bad or revoked (MCP: connection not authorized, or its token expired). Fix the header or make a new key. |
no_workspace | 403 | no | The account has no workspace. Create one in the app, then reconnect. |
connection_not_configured | 403 | no | MCP only. The account has several workspaces. Send the person to connect_url to pick one. |
workspace_unavailable | 410 | no | The key's workspace is gone, so the key never works again. |
required_plan | 403 | no | The plan lacks the agent API or this capability. Pick another, or a person upgrades. |
read_only_connection | 403 | no | A read-only connection tried to start work. Reconnect with spend access. |
insufficient_scope | 403 | no | REST only. The key lacks the scope named in the message. Create a key with it. |
invalid_config | 400 | no | Bad body, unknown key, bad list filter, or an import link that is not a direct file. The message names up to 5 issues. Schemas: Capabilities. |
capability_unavailable | 404 | no | Capability id unknown, retired or not live yet. Check capability_status, then list capabilities. |
not_found | 404 | no | Unknown id, another workspace's id, a file not ready yet, or an unknown /api/v1 path. It never says which. |
input_not_ready | 409 | yes | An upload is still in its safety scan. Wait a moment, send again. |
insufficient_credits | 402 | no | Not enough credits. A person tops up in the app. |
max_credits_exceeded | 402 | no | Your max_credits is too low. Send the estimate's max_credits_needed (or limit.required_credits). On a workflow run it covers every step. |
spend_limit_exceeded | 402 | no | A workspace or key spend cap blocked it. Ask a workspace owner or admin. |
estimate_changed | 409 | yes | The price moved. Estimate again, raise max_credits if needed, resend. |
not_priced | 409 | no | This capability cannot be priced yet. Use another one. |
pricing_unavailable | 503 | yes | Pricing failed for a moment. Retry shortly. |
moderation_blocked | 422 | no | Refused by content policy. The same request is refused again: Content. |
moderation_unavailable | 503 | yes | Content checks are down, so nothing can start. Reads still work. |
rate_limited | 429 | yes | Too many requests, uploads or renders at once. Wait retry_after_seconds, else back off. Limits. |
quota_exceeded | 429 | no | Too many uploads are still unfinished in this workspace. Finalize them, or wait for abandoned ones to clear. |
submission_in_flight | 409 | yes | Something is already running. Wait on it, don't resend. See below. |
request_blocked | 429 | no | This exact request is blocked after repeated failures. Send a different one. See below. |
provider_unavailable | 502 | yes | A provider failed, or an import link's host did not answer. Back off, retry. |
internal_error | 500 | yes | Our fault. Retry at most twice, then stop. |
8 codes are retryable and 17 are not.
The HTTP status does not tell you to retry
rate_limited, quota_exceeded and request_blocked are all 429. Only rate_limited is retryable, so read retryable.
Codes with more than one cause
submission_in_flight
| Cause | Extra field | Do |
|---|---|---|
| This API key (or MCP person) already has a job running | in_flight | Wait on in_flight.generation_id with GET /generations/{id}/wait. |
| Someone in the workspace sent the identical request first | retry_after_seconds: 30 | Wait for theirs, or change the request. Nothing was charged. |
| The workflow already has a run in flight | none | Wait for that run to finish. |
request_blocked
| Kind | Armed after | Lasts | retry_after_seconds |
|---|---|---|---|
| Transient | 3 failures (provider_unavailable, internal_error, or a content refusal from a model) | about 1 hour | yes |
| Permanent | 2 content refusals from the rule list | 30 days | no |
Both are retryable: false, so change the script or inputs. Extra junk fields don't help: unknown keys are refused first.
rate_limited from too many renders at once has no retry_after_seconds. Wait for a job to finish.
moderation_blocked on a file names its ast_ id. That file can never be used, so upload a different one.
Retry rules
When to retry and when to stop: Refusals and retries. This loop follows those rules.
async function submit(body: unknown, attempt = 0): Promise<unknown> {
const res = await fetch("https://app.riffads.com/api/v1/generations", {
method: "POST",
headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
body: JSON.stringify(body),
});
const json = await res.json();
if (res.ok) return json;
const e = json.error;
if (!e.retryable) throw new Refused(e.code, e.message);
if (e.code === "submission_in_flight" && e.in_flight) {
return waitFor(e.in_flight.generation_id);
}
if (attempt >= 2) throw new Refused(e.code, e.message);
await sleep((e.retry_after_seconds ?? 2 ** attempt) * 1000);
return submit(body, attempt + 1);
}A refusal is not a failed generation
A refusal started nothing. A job that was accepted and then failed reads status: "failed" with its own error: Generation status.
Answers that are not the envelope
| Answer | Shape |
|---|---|
Per-IP 429 on MCP and GET /health/ready | OAuth shape (below), with Retry-After. Keyed /api/v1 routes have none. Per IP |
GET /health, GET /health/ready | ok plus status. A failing readiness check is 503 with status: "unavailable", no code. Health |
| A failed webhook delivery | Never sent to you. It is retried, and its history is on the Webhooks settings page. Webhooks |
The per-IP 429 body:
{
"error": "too_many_requests",
"error_description": "Too many requests from this address. Please wait and try again."
}Codes that don't exist
No bad_request, conflict, forbidden, unauthorized, server_error, timeout, payload_too_large or unsupported_media_type.