Errors

Brain separates failures into three distinct error layers so your application can tell whether an HTTP request was rejected, a tool call failed during a turn, or the turn itself stopped:

• Client request errors (4xx / 500 HTTP responses): Reject bad inputs, missing permissions, or capacity limits without breaking a healthy session.
• Tool errors (tool.result events): Tool failures become tool results (result.is_error: true) so the model can inspect the error and decide how to proceed.
• Execution errors (session.error events): Brain errors and model provider failures stop the affected execution and move the session to interrupted or failed.

HTTP error shapeCopy Anchor Link

Every failed HTTP request returns a JSON error envelope containing error.code, error.message, and request_id:

{
  "error": {
    "code": "conflict",
    "message": "resume the interrupted session before sending input"
  },
  "request_id": "a1b2c3d4e5f60718293a4b5c6d7e8f90"
}

In the TypeScript and Python SDKs, non-2xx HTTP responses raise BrainError with status, code, message, and requestId / request_id.

HTTP status codesCopy Anchor Link

Request IDsCopy Anchor Link

Every HTTP response includes an X-Request-ID header (a 32-character hex ID). When a request fails, the same value is returned in the JSON body's request_id field, and 500 responses log "request failed" with request_id to stderr. Include request_id whenever diagnosing failed requests.

Retries and Retry-AfterCopy Anchor Link

• HTTP client requests: Neither the TypeScript SDK nor the Python SDK retries failed HTTP requests automatically. When Brain returns 429 overloaded, it sets the Retry-After: 1 response header. When retrying POST /sessions/{id}/events, pass the same idempotency key on your user.message so duplicate submissions return the originally recorded event instead of queueing a second turn.
• Tool dispatches: Brain never retries tool calls automatically. A transient network failure or timeout on a tool call is reported to the model so the harness or tool service can decide whether retrying is safe.

Tool errors (tool.result)Copy Anchor Link

Tool errors do not fail the HTTP request or stop the turn. When a tool call is denied, fails input/output schema validation, returns a non-2xx HTTP status, outputs invalid JSON, exceeds max_output_bytes, or times out, Brain records a tool.result event with result.is_error: true and passes the error text back to the harness:

{
  "call_id": "CALL_ID",
  "result": {
    "content": [{ "type": "text", "text": "tool transport failed; remote outcome may be unknown" }],
    "is_error": true,
    "unknown_outcome": true
  }
}

• unknown_outcome: false (omitted): The failure happened before the tool service received the request (for example, unauthorized tool, schema validation error, missing local credential, or MCP connection failure before dispatch). No remote side effect occurred.
• unknown_outcome: true: The failure happened after Brain sent the request (for example, network drop, timeout, HTTP 5xx, oversized response, or broken SSE stream). The remote side effect may have already happened.

Session errors (session.error)Copy Anchor Link

When an execution failure stops a turn (or cancels a queued message), Brain emits a retained session.error event with input_id set to the affected user.message id, followed by a session.status event:

To continue a session after it enters interrupted or failed, call POST /sessions/{id}/resume (brain.resume(id)) to reset the session to idle at its last completed checkpoint before sending new input.