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.
{
"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
| Status | error | Means | Retry |
|---|---|---|---|
| 400 | bad_request | The 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 |
| 401 | unauthorized | No key, a key in the wrong shape, or a key that is revoked or expired. | Fix, do not retry |
| 403 | forbidden | The 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 |
| 404 | not_found | No such route, or no such object in this account. An id from another account answers exactly like this. | Fix, do not retry |
| 409 | conflict | The request conflicts with the current state, such as a person already on the account. | Fix, do not retry |
| 409 | refused | A 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 |
| 500 | internal | Something went wrong on our side. | With backoff |
| 502 | upstream_failed | Something 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
Handling errors
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.