Error codes

All errors are returned as:

{
  "error": {
    "type": "https://docs.mnemosyne.dev/api-reference/errors#code",
    "code": "string",
    "message": "human-readable explanation",
    "param": "optional — parameter that caused the error",
    "details": {},
    "request_id": "req_xxx"
  }
}

4xx — Client errors

400 invalid_request

Request body failed schema validation. Check the OpenAPI schema for the endpoint.

400 unknown_field

Body contained a field Mnemosyne does not recognise. Remove it or pin your client to an older API version.

401 missing_bearer_token

No Authorization header. Add Authorization: Bearer mns_live_xxx.

401 invalid_bearer_token

The bearer token doesn’t exist or was revoked. Rotate with mnemo keys rotate.

403 workspace_mismatch

The workspace is derived from your API key. You hit this when the targeted resource belongs to a different workspace than the one your key is bound to. Use a key for the owning workspace.

403 insufficient_scope

The key lacks the required scope. Grant memory:write, memory:admin, etc.

404 not_found

Resource doesn’t exist in this workspace. Verify the ID and the workspace.

409 conflict_detected

A write would create an unresolvable conflict. Inspect the review queue, then re-submit.

409 idempotency_replay_mismatch

Same Idempotency-Key was used with different parameters. Generate a new key per logical request.

422 validation_failed

Schema OK but business rules failed (for example, invalid bitemporal window). Check the details field.

429 rate_limited

You exceeded the per-key rate limit. Honour the Retry-After header.

451 data_residency

Workspace is region-locked and the request came from another region. Route through the correct region.

5xx — Server errors

500 internal_error

Unhandled exception. Always paged. Report the request_id; retries are safe.

501 embedding_required

The endpoint needs a vector but no embedding provider is configured. Configure Mode B or C.

502 embed_provider_down

The configured embedding provider returned an error. Retry with backoff — the circuit breaker may demote to Mode A automatically.

503 degraded

A non-critical component is unhealthy. Recall still works. Check /v1/health/deep.

504 upstream_timeout

An upstream LLM or embed call timed out. Reduce topK or increase the timeout.

Envelope evolution

We don’t break the envelope. Adding new top-level fields is allowed; renaming or removing them requires a new API version with a backwards-compat layer. Same rule Stripe uses.