Errors and request limits
The daemon error envelope, status mapping, service availability, and source-defined request limits.
Error envelope
Handlers using DaemonError return a JSON object with code and message:
{
"code": "error",
"message": "invalid id"
}The example shows the envelope, not a universal message. Do not rely on the text of a message as a stable machine-readable error identifier.
| Source variant | HTTP status | code |
|---|---|---|
| InvalidRequest | 400 | error |
| Unauthorized | 401 | error |
| Forbidden | 403 | error |
| NotFound | 404 | error |
| PayloadTooLarge | 413 | working_memory_value_too_large |
| Overloaded | 429 | cognitive_runtime_capacity_exceeded |
| WorkingMemoryCapacity | 429 | working_memory_capacity_exceeded |
| Internal | 500 | error |
| DataCorruption | 500 | data_corruption |
| ServiceDisabled | 503 | error |
| Timeout | 504 | error |
The rate-limit middleware has its own 429 envelope: {"code":"rate_limited","message":"too many requests"}. Axum JSON/path/query extraction failures, unknown routes, unsupported methods, and raw responses can use different bodies. The generated operation reference lists error variants explicitly referenced by each handler; downstream calls can add further errors.
Service availability
There are two gates. At startup, the router conditionally registers most feature families from ServiceConfig. At request time, a service-prefix middleware checks whether the corresponding service is currently enabled. A missing registration can produce 404; an available route whose service or dependency is disabled can return 503.
Health routes ending in /health or /health/startup bypass the runtime service middleware, but their handlers may still report a missing dependency. Working-memory and cognitive-control routes have additional handler-level availability and authority checks. Model-manager routes are registered even when manager initialization failed; those requests return a service-disabled error.
Request size and rate limits
| Setting | Source default | Scope |
|---|---|---|
AKASHA_REQ_MAX_BYTES | 10,000,000 bytes | Axum default body limit; individual operations can enforce smaller limits. |
AKASHA_RATE_LIMIT_RPS | 1,000 | A direct rate limiter shared by the instance state, not a separate quota per API key. |
| Cognitive-cycle input | 1,000,000 bytes | Handler-defined serialized input limit. |
| Cognitive trigger | 256 bytes | Handler-defined trigger limit. |
| MIND embedding dimensionality | 65,536 | Receiver schema bound; vector components must be finite and the declared dimension must match the vector length. |
These are configuration/default facts, not throughput benchmarks. A lifecycle soft ceiling can also pause work and return 429; the current source routes that condition through Overloaded.
Recovery and retries
The reference does not claim a global idempotency-key contract. A retry of a mutation can have effects unless the specific handler implements duplicate detection or idempotent behavior. Read the operation’s validation and mutation sequence before adding automatic retries. A generic 500, 503, or connection failure does not establish that a write was never applied.
Source: akasha-daemon/src/main.rs (DaemonError::into_response, rate_limit_layer, runtime_service_middleware, Cli, and cognitive-cycle constants); akasha-daemon/src/mind_receiver.rs.