Skip to main content
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

StatusMeaning
400Bad request — malformed JSON, missing required field, invalid value.
401Unauthenticated — X-Engine-Key missing or invalid.
403Authenticated but not allowed to perform this operation.
404Resource doesn’t exist.
409Conflict — the resource is in a state that prevents this operation.
422Validation error — schema-level problem with the request.
429Rate-limited — back off.
500Internal server error — unexpected failure. Report it.
502Upstream LLM provider returned an error the Engine couldn’t recover from.
503Engine is starting up, draining, or otherwise temporarily unavailable.
504Upstream 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:
CodeWhen
INVALID_KEYX-Engine-Key is missing or doesn’t match.
KEY_ROTATION_PENDINGKey was rotated; old key was used during the overlap window. Retry with the new key.
TASK_NOT_FOUNDA task_id referenced doesn’t exist.
HITL_REQUIREDThe agent paused on a HITL request; respond with /hitl/respond before continuing.
LLM_PROVIDER_ERRORThe upstream LLM provider returned a non-recoverable error.
LLM_RATE_LIMITEDThe upstream LLM provider rate-limited the call.
CONTEXT_OVERFLOWThe agent’s context exceeded what compaction could recover.
PERMISSION_DENIEDThe agent (or you) tried to do something the permission system blocked.
MCP_CONNECTION_FAILEDAn Asset Directory connection attempt failed.
MCP_TOKEN_EXPIREDA connection’s credentials expired and refresh failed.
MIGRATION_REQUIREDThe 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

CodeRetry?How
LLM_RATE_LIMITEDYesExponential backoff, starting at 1s.
LLM_PROVIDER_ERRORSometimesRetry once with the same task_id. If it fails again, surface to the user.
KEY_ROTATION_PENDINGYesRetry with the new key.
MCP_TOKEN_EXPIREDNoReconnect through /assets/connect for the affected ref_id.
CONTEXT_OVERFLOWNoStart a fresh task or trim the conversation.
INVALID_KEYNoFix the key.
503YesBack off; the Engine may be starting up.

​
See also