Errors

Shape

Errors are returned as JSON with a message describing what went wrong:

{
  "error": "Invalid or expired token"
}

Streaming (SSE) endpoints emit an error event with the same shape instead of an HTTP error status, since the response has already started streaming.

Common status codes

Status	Meaning
400	Malformed request — check required fields and types.
401	Missing or invalid authentication token.
402	Insufficient balance to run the requested agent action — your wallet is empty, or a team budget has hit its member limit, monthly ceiling or empty pool.
403	Authenticated, but not allowed to access this resource — including a team action your role does not permit.
404	Resource not found (or you don't have access to it).
409	Conflicting state — for example, a suspended team, or deleting a team that still holds funds.
413	Request body too large (for example, an oversized attachment).
429	Rate limited — back off and retry.
503	A billing target could not be read safely. The server refuses rather than guessing with your money — retry.
5xx	Server error — safe to retry with backoff; if it persists, it's on us.

Retrying safely

Network interruptions during a long-running agent stream (a build, a chat turn) are common and expected — the official clients (CLI, VS Code extension) automatically detect a dropped connection mid-stream and transparently reconnect without losing your place. If you're calling the streaming API directly, treat a mid-stream disconnect as retryable and resume rather than restarting the whole request from scratch.