Errors

Every refusal code, its HTTP status, whether to retry, and what to do.

Read as Markdown

Your call was refused. Find its code below and do what the row says.

The error body

Same object on REST, MCP and the CLI.

Response: 404
{
  "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
  }
}
FieldTypeWhat it is
okfalseAlways false on a refusal.
codestringOne of the 25 codes below. Branch on it.
messagestringOne safe sentence. Show it, never parse it: the wording can change.
retryablebooleanMay you send the identical request again.
credits_chargednumberWhat this refused call cost. Almost always 0.

Some codes add fields. A field that is not set is left out, never null.

FieldOnUse
retry_after_secondsrate_limited, transient request_blocked, submission_in_flight (race)Seconds to wait.
in_flightsubmission_in_flight (one per key)generation_id and status of the job already running. Wait on it.
blocked_reasonrequest_blockedThe code that got this request blocked.
capability_statuscapability_unavailable, required_plancoming_soon, retired, requires_plan or unknown.
required_planrequired_planThe plan that unlocks it, when known.
shortfallinsufficient_creditsCredits missing.
limitmax_credits_exceeded, spend_limit_exceededWhich cap refused, in limit.bound_by. Spend limits.
connect_urlconnection_not_configured (MCP only)Page where a person picks the workspace.

Where it arrives

SurfaceShape
RESTUnder error, with the HTTP status from the table. A 429 with retry_after_seconds also sends Retry-After.
MCPThe whole object (no error wrapper) as JSON in one text block, with isError: true.
CLISentence and code on stderr. --json prints the same object, under error, on stdout. Exit codes: Commands.

All codes

CodeHTTPRetryableWhat to do
not_authorized401noKey missing, bad or revoked (MCP: connection not authorized, or its token expired). Fix the header or make a new key.
no_workspace403noThe account has no workspace. Create one in the app, then reconnect.
connection_not_configured403noMCP only. The account has several workspaces. Send the person to connect_url to pick one.
workspace_unavailable410noThe key's workspace is gone, so the key never works again.
required_plan403noThe plan lacks the agent API or this capability. Pick another, or a person upgrades.
read_only_connection403noA read-only connection tried to start work. Reconnect with spend access.
insufficient_scope403noREST only. The key lacks the scope named in the message. Create a key with it.
invalid_config400noBad 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_unavailable404noCapability id unknown, retired or not live yet. Check capability_status, then list capabilities.
not_found404noUnknown id, another workspace's id, a file not ready yet, or an unknown /api/v1 path. It never says which.
input_not_ready409yesAn upload is still in its safety scan. Wait a moment, send again.
insufficient_credits402noNot enough credits. A person tops up in the app.
max_credits_exceeded402noYour 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_exceeded402noA workspace or key spend cap blocked it. Ask a workspace owner or admin.
estimate_changed409yesThe price moved. Estimate again, raise max_credits if needed, resend.
not_priced409noThis capability cannot be priced yet. Use another one.
pricing_unavailable503yesPricing failed for a moment. Retry shortly.
moderation_blocked422noRefused by content policy. The same request is refused again: Content.
moderation_unavailable503yesContent checks are down, so nothing can start. Reads still work.
rate_limited429yesToo many requests, uploads or renders at once. Wait retry_after_seconds, else back off. Limits.
quota_exceeded429noToo many uploads are still unfinished in this workspace. Finalize them, or wait for abandoned ones to clear.
submission_in_flight409yesSomething is already running. Wait on it, don't resend. See below.
request_blocked429noThis exact request is blocked after repeated failures. Send a different one. See below.
provider_unavailable502yesA provider failed, or an import link's host did not answer. Back off, retry.
internal_error500yesOur 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

CauseExtra fieldDo
This API key (or MCP person) already has a job runningin_flightWait on in_flight.generation_id with GET /generations/{id}/wait.
Someone in the workspace sent the identical request firstretry_after_seconds: 30Wait for theirs, or change the request. Nothing was charged.
The workflow already has a run in flightnoneWait for that run to finish.

request_blocked

KindArmed afterLastsretry_after_seconds
Transient3 failures (provider_unavailable, internal_error, or a content refusal from a model)about 1 houryes
Permanent2 content refusals from the rule list30 daysno

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.

submit.ts
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

AnswerShape
Per-IP 429 on MCP and GET /health/readyOAuth shape (below), with Retry-After. Keyed /api/v1 routes have none. Per IP
GET /health, GET /health/readyok plus status. A failing readiness check is 503 with status: "unavailable", no code. Health
A failed webhook deliveryNever sent to you. It is retried, and its history is on the Webhooks settings page. Webhooks

The per-IP 429 body:

Response: 429 per IP
{
  "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.

On this page