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.
403	Authenticated, but not allowed to access this resource.
404	Resource not found (or you don't have access to it).
413	Request body too large (for example, an oversized attachment).
429	Rate limited — back off and 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.