Errors

Every error uses the OpenAI envelope. code is the machine-readable part — branch on it, not on the message text, which we reserve the right to improve.

{
  "error": {
    "message": "Insufficient credits. Top up to continue.",
    "type": "insufficient_credits",
    "code": "insufficient_credits"
  }
}

Some errors add fields alongside message, type and code. hold_exceeds_balance is the one that does today.

API errors

These are the codes a client calling https://api.shardio.ai/v1 can receive.

A 429 always carries a Retry-After header, in seconds. A 429 is also recorded in your request history, so a throttled minute is visible after the fact; a 401 or 402 is not recorded.

The three server-side codes, and how they differ

They look similar and mean different things, which matters when you decide whether to retry:

• no_capacity (503) — no node was ever reached. Zero cost, always safe to retry.
• upstream_failed (502) — a node ran the request and failed it. Safe to retry, but it costs a second generation, and the first is billed only for output that reached you.
• upstream_stall (502) — a node went quiet. Usually you hold partial output and a retry produces a whole second answer; it also arrives with no output at all when neither the first attempt nor the retry produced a single token. In that case nothing reached the gateway and nothing was billed.

On a streamed request none of these can be an HTTP status, because the response already committed to 200. They arrive as a terminal error event instead — see Streaming.

Console errors

These come from the console API, which authenticates with a signed-in session rather than an API key. There is no console site in front of it yet, so you will only see these if you are calling that API directly.

Buying credits

Node errors

These come from the /agent API that the shardio CLI uses. They surface as CLI output rather than as raw JSON; see Join the mesh.