Error codes

Your call was refused. Find the code below. 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 id returned by submit_generation.",
    "retryable": false,
    "credits_charged": 0
  }
}

Extra fields appear only on some codes. They are left out when not set, never null.

Where it arrives

All codes

8 codes are retryable. 17 are not.

Codes with more than one cause

submission_in_flight

request_blocked

Both are retryable: false. Change the script or inputs. Adding junk fields does not make it a new request: unknown keys are refused first.

rate_limited from too many renders at once has no retry_after_seconds. Wait for a job to finish, then back off.

moderation_blocked on a file names the asset id (ast_...). That file can never be used. Upload a different one.

Retry rules

• retryable: false: never send that request again. Not after a wait, not with a new key. Change it or stop.
• retryable: true: at most two more attempts. Honor retry_after_seconds, else back off. Then stop.
• Lost the response? Don't resubmit to find out. A second submit can be a second charge. Read the generation instead.

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

• Refusal: the submit did not happen. Nothing started.
• Failed generation: the submit was accepted (201), then the job failed. You see it on a read: status: "failed" and error: { code, message }. That code can be null. Results.

The one 429 with a different shape

The MCP host has a per-IP brake that answers before auth. It is OAuth shaped, with Retry-After. /api/v1 is not behind it.

{
  "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, unsupported_media_type. Another workspace's id answers not_found, never forbidden.