Errors - Docs

When something goes wrong, the Engine returns a non-2xx HTTP status with a JSON body of the form:

{
  "error": "<error_code>",
  "message": "<human-readable description>",
  "details": { /* optional, structured */ }
}

The error field is a stable, machine-readable identifier. The message is for humans. Use error for routing logic; show message (or your own translation of the code) to end users.

HTTP status taxonomy

Status	Meaning
`400`	Bad request — malformed JSON, missing required field, invalid value.
`401`	Unauthenticated — `X-Engine-Key` missing or invalid.
`403`	Authenticated but not allowed to perform this operation.
`404`	Resource doesn’t exist.
`409`	Conflict — the resource is in a state that prevents this operation.
`422`	Validation error — schema-level problem with the request.
`429`	Rate-limited — back off.
`500`	Internal server error — unexpected failure. Report it.
`502`	Upstream LLM provider returned an error the Engine couldn’t recover from.
`503`	Engine is starting up, draining, or otherwise temporarily unavailable.
`504`	Upstream LLM provider timed out.

Common error codes

The Engine emits its own error codes from src/errors.py. The most common ones you’ll see:

Code	When
`INVALID_KEY`	`X-Engine-Key` is missing or doesn’t match.
`KEY_ROTATION_PENDING`	Key was rotated; old key was used during the overlap window. Retry with the new key.
`TASK_NOT_FOUND`	A `task_id` referenced doesn’t exist.
`HITL_REQUIRED`	The agent paused on a HITL request; respond with `/hitl/respond` before continuing.
`LLM_PROVIDER_ERROR`	The upstream LLM provider returned a non-recoverable error.
`LLM_RATE_LIMITED`	The upstream LLM provider rate-limited the call.
`CONTEXT_OVERFLOW`	The agent’s context exceeded what compaction could recover.
`PERMISSION_DENIED`	The agent (or you) tried to do something the permission system blocked.
`MCP_CONNECTION_FAILED`	An Asset Directory connection attempt failed.
`MCP_TOKEN_EXPIRED`	A connection’s credentials expired and refresh failed.
`MIGRATION_REQUIRED`	The brain database is at an older schema than the running Engine.

Streaming errors

Inside an SSE stream from /execute, errors arrive as events, not HTTP status codes:

event: error
data: {"error": "LLM_PROVIDER_ERROR", "message": "..."}

After an error event, the stream is over. You’ll need to make a new /execute call to retry or continue.

Retry guidance

Code	Retry?	How
`LLM_RATE_LIMITED`	Yes	Exponential backoff, starting at 1s.
`LLM_PROVIDER_ERROR`	Sometimes	Retry once with the same `task_id`. If it fails again, surface to the user.
`KEY_ROTATION_PENDING`	Yes	Retry with the new key.
`MCP_TOKEN_EXPIRED`	No	Reconnect through `/assets/connect` for the affected ref_id.
`CONTEXT_OVERFLOW`	No	Start a fresh task or trim the conversation.
`INVALID_KEY`	No	Fix the key.
`503`	Yes	Back off; the Engine may be starting up.

See also

Authentication for INVALID_KEY and rotation errors.
Streaming events for the error event in SSE.
Build with the Engine → Error handling for end-to-end retry patterns.