Documentation Index
Fetch the complete documentation index at: https://septemberai.mintlify.app/llms.txt
Use this file to discover all available pages before exploring further.
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 */ }
}
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": "..."}
/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
