# Errors and request limits

The daemon error envelope, status mapping, service availability, and source-defined request limits.

Source: https://docs.minds.sh/docs/api/instance/errors



## Error envelope [#error-envelope]

Handlers using `DaemonError` return a JSON object with `code` and `message`:

```json
{
  "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 [#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 [#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 [#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`.