Errors, responses, and retries
Read the actual response shape, distinguish accepted work from completion, and retry only when safe.
Always inspect the HTTP status before reading a result. The platform has several response styles because its browser, management, and instance surfaces serve different clients.
Success is not universally wrapped
The management helper apiSuccess(data) returns data directly. It does not automatically add {data:...}. A service's own response type may contain data, tenants, or another collection field. Instance listing returns a raw array. Dashboard provisioning returns {instance}. Proxies preserve the upstream body.
| Status | Usual meaning |
|---|---|
| 200 | A read or synchronous operation returned a result |
| 201 | A resource was created by this route |
| 202 | An asynchronous operation was accepted, or a dashboard readiness check is still pending |
| 204 | Success with no response body |
A 202 creation, backup, or restore response does not mean that the provider operation has finished.
Management errors
Routes using apiError() return this shape:
{
"error": {
"code": "INVALID_REQUEST",
"message": "Invalid request body",
"details": { "validation_errors": [] },
"request_id": "<request-id>"
}
}| Status | Common code | Action |
|---|---|---|
| 400 | INVALID_REQUEST | Correct the request fields, types, or referenced resources |
| 401 | AUTHENTICATION_REQUIRED | Supply a valid credential for this API surface |
| 403 | PERMISSION_DENIED | Check organization membership and credential scope |
| 404 | RESOURCE_NOT_FOUND | Verify the resource ID in the authorized scope |
| 409 | CONFLICT | Reload current state before deciding whether to retry |
| 429 | RATE_LIMIT_EXCEEDED | Honor Retry-After when present |
| 500 | INTERNAL_ERROR, PROVISIONING_FAILED | Preserve the request ID and inspect resource/provider state |
| 503 | SERVICE_UNAVAILABLE | Retry a safe read after backoff or wait for the service to recover |
Some route-specific codes extend this set. Dashboard routes also use {error:string} and {error:{code,message}}; do not assume all bodies validate against the management error schema.
Validation
The management service parses request bodies and queries with the schemas in Schema reference. Malformed JSON and invalid fields produce 400. Optional fields and defaults are explicit in the schemas. Query parameters arrive as strings, so coercion is available only where the schema defines it.
Request and rate-limit metadata
Management routes that call withRequestMetadata() add X-Request-ID. Their rate-limit results may also add X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, and Retry-After. Keep the request ID with your own diagnostic event; never include the credential.
Retry behavior
Retry read-only requests with bounded backoff. For a timeout after a create, scale, delete, restore, or billing operation, inspect the resource before repeating the mutation. The first request may have reached the provider even when the client received no success response.
Tenant and service creation read Idempotency-Key. The current helper stores a response under the supplied key for 24 hours, but the source does not establish request-body binding or a transaction spanning provider work. Use a unique key per logical operation and do not describe this implementation as exactly-once processing.
Instance tool errors
The dedicated daemon's MCP HTTP tool endpoint can return an HTTP-success response with is_error:true in its tool envelope. Check both levels:
if (!response.ok) throw new Error(`HTTP ${response.status}`);
const output = await response.json();
if (output.is_error) throw new Error('The memory tool rejected the operation');Source: minds-ui/apps/api-service/types/errors.ts, lib/api-response.ts, lib/validation.ts, lib/idempotency.ts, and akasha/mcp/src/tools/mod.rs.