Guides

Errors

Every error has the same shape: a stable code for your program, a sentence for the person reading the log, and a request id.

The shape

A request that did not succeed is answered with a 4xx or 5xx status and a JSON body. Branch on error, which does not change. Show or log message, which is written for a person and may be reworded. detail, when present, holds the facts behind it, and requestId finds the request in our logs.

409 Conflict
{
  "error": "refused",
  "message": "the agent kill switch is engaged: Pausing while we change its brief",
  "detail": { "killSwitch": "4b8e1f63-9a2d-4c75-8e0b-3f7a6d2c9e15", "scope": "agent" },
  "requestId": "req-7c"
}

Status codes

StatuserrorMeansRetry
400bad_requestThe request is not valid: the body is not JSON, a field is missing, wrong, or not allowed. detail.issues lists each one.Fix, do not retry
401unauthorizedNo key, a key in the wrong shape, or a key that is revoked or expired.Fix, do not retry
403forbiddenThe key does not hold the scope this route needs (detail.required names it), the caller’s role may not do this, or the route is a person’s to decide.Fix, do not retry
404not_foundNo such route, or no such object in this account. An id from another account answers exactly like this.Fix, do not retry
409conflictThe request conflicts with the current state, such as a person already on the account.Fix, do not retry
409refusedA guard said no: a kill switch, an archived agent, a deadline over the maximum, an approval that expired or was edited since you saw it. Retrying cannot help.Fix, do not retry
500internalSomething went wrong on our side.With backoff
502upstream_failedSomething behind the API failed, such as the AI gateway.With backoff

A refusal is not a failure

A failure (500, 502) means we tried and something broke, so a retry later may work. A refusal (refused, and every other 4xx) means a rule said no, and sending the same request again will be refused again. Fix the request, or tell the person.

Every refusal is recorded

A request refused for its scope, its role or a guard is written to the account's audit log with the route and the reason, so an owner can see what an integration tried.

Handling errors

TypeScript
const res = await fetch(url, init);
if (!res.ok) {
  const { error, message, requestId } = (await res.json()) as { error: string; message: string; requestId?: string };
  // 5xx: something broke on our side; retry later with backoff.
  // Everything else: a rule said no; fix the request instead of retrying it.
  throw new Error(`Rykon AI ${res.status} ${error}: ${message} (${requestId ?? 'no id'})`);
}

Rate limits

The API does not publish per-key rate limits yet; they arrive with the hosted endpoint and will be documented here first. Runs are bounded by their deadline and turns, and model spend by the account's daily ceiling, which a run that reaches it reports as its failure reason.