🔗Envelope & errors

Every /api/v1 response the daemon returns is wrapped in one of two envelopes. Success bodies carry their payload under data; error bodies carry an error detail under error. Both always include a meta block with the API version, a correlation ID, and a generation timestamp. This page is the canonical contract for those shapes and for the ErrorCode to HTTP status mapping. Every endpoint in the REST reference returns one of these two envelopes, so the shapes are documented once here and linked from each route.

The whole envelope lives in a single file, api/envelope.rs, and is generated by ApiResponse<T> (success) and ApiError (failure). There is no per-endpoint variation in the wrapper.

🔗Success envelope

A successful response is { data, meta }. The data field holds the endpoint-specific payload; the meta block is identical in shape across every response.

{
  "data": {
    "id": "borealis",
    "name": "Borealis",
    "category": "ambient"
  },
  "meta": {
    "api_version": "1.0",
    "request_id": "req_0190d4c8-7e21-7c3a-9f0b-3a2e8c1d4f56",
    "timestamp": "2026-06-24T18:03:11.482Z"
  }
}

The daemon emits three success statuses, depending on the operation:

All three carry the same { data, meta } body. The status line is the only difference, so a client that only inspects the body sees a uniform shape.

🔗Error envelope

A failed response is { error, meta }. The top-level key is error, not data, so the presence of data versus error is the cleanest discriminator a client can branch on.

{
  "error": {
    "code": "validation_error",
    "message": "speed must be between 0.0 and 2.0",
    "details": {
      "field": "speed",
      "min": 0.0,
      "max": 2.0
    }
  },
  "meta": {
    "api_version": "1.0",
    "request_id": "req_0190d4c8-9a13-7b88-a0f2-5e6d7c8b9a01",
    "timestamp": "2026-06-24T18:03:12.118Z"
  }
}

The error object has three fields:

Branch on code, render message, and read details when you need the specifics. Never parse message to decide control flow; it is prose and can change.

🔗The meta block

The meta block is attached to every envelope, success or error, and never varies in shape.

🔗Error codes and HTTP status

Every error maps to exactly one HTTP status. The code string in the body and the HTTP status line always agree, so a client can switch on either. The full set of codes lives in the ErrorCode enum in api/envelope.rs; this is the complete mapping.

🔗Status flow

The same ErrorCode value drives both the body and the response status. There is no path where they disagree.

graph LR
  H[Handler] -->|ApiError::validation| C[ErrorCode::ValidationError]
  C -->|serialize| B["body.error.code = validation_error"]
  C -->|status map| S["HTTP 422"]

🔗Rate-limit responses

A rate_limited error (HTTP 429) carries extra signal beyond the envelope. The daemon attaches a details.retry_after field (seconds until the window resets) and a set of response headers so a client can back off precisely instead of guessing.

{
  "error": {
    "code": "rate_limited",
    "message": "discovery rate limit exceeded. Retry in 12 seconds.",
    "details": {
      "retry_after": 12
    }
  },
  "meta": {
    "api_version": "1.0",
    "request_id": "req_0190d4c8-c0de-7a44-8b91-77aa55ee33cc",
    "timestamp": "2026-06-24T18:03:14.902Z"
  }
}

The accompanying headers:

Prefer Retry-After (or the equal details.retry_after) for backoff timing. Throttling is a property of specific operation classes, so a 429 on one endpoint does not mean every endpoint is throttled.

🔗Handling errors in a client

A robust client follows the same three steps regardless of language.

1. Check for the error key (or equivalently, a non-2xx status). If present, you have a failure envelope.
2. Switch on error.code. The string is stable; the HTTP status is its mirror.
3. Read error.details for structured context, and on a 429 honor Retry-After. Always capture meta.request_id so a failure can be correlated with the daemon logs.

# Inspect the envelope of any endpoint with curl + jq.
curl -s http://localhost:9420/api/v1/effects/does-not-exist \
  | jq '{status_code: .error.code, message: .error.message, request_id: .meta.request_id}'
# => { "status_code": "not_found", "message": "...", "request_id": "req_..." }

For the routes that return these envelopes, see the REST API reference. For the real-time channel and its own framing, see the WebSocket protocol.