> api errors

error reference

every error the memra api returns links here. find the code, read what it means, fix it.

‹ 01 ›

the error envelope

most errors arrive in a nested envelope. the docs field is a deep link back to this page. 

{
  "error": {
    "code": "project_not_found",
    "message": "No project with this ID exists in your account",
    "docs": "https://usememra.com/docs/errors#project_not_found"
  }
}

two middleware errors — rate_limit_exceeded and quota_exceeded — predate that envelope and return error as a flat string with sibling fields. both shapes are shown below. always branch on the http status first, then on the code.

‹ 02 ›

> auth & access

invalid_api_key HTTP 401

The Authorization header is missing, malformed, or the key was revoked.

fix • Send Authorization: Bearer memra_live_…. Keys are shown once at creation — generate a new one in the dashboard if it is lost.

email_unverified HTTP 403

The account behind this key has not confirmed its email address.

fix • Open the verification link in your inbox. Reads stay open while unverified; writes are blocked.

read_only_key HTTP 403

A read-only key attempted a write.

fix • Recall, get, list, bootstrap and export work with read-only keys. Use a read-write key for add, update, supersede and delete.

forbidden HTTP 403

The resource exists but does not belong to this account, or the route requires admin.

fix • Check that the ID came from this account. Cross-account IDs are never readable.

> limits & billing

rate_limit_exceeded HTTP 429

Too many requests for your tier in the current window.

fix • Back off for retry_after seconds. X-Memra-RateLimit-Reset carries the reset timestamp.

quota_exceeded HTTP 429

A plan resource (memories, projects, tenants) is at its ceiling.

fix • The body names the resource, current and limit. Upgrade at the URL in X-Memra-Limit-Upgrade.

project_limit_reached HTTP 403

The account is at its project ceiling for its tier.

fix • Delete an unused project or upgrade the plan.

tenant_limit_reached HTTP 403

The account is at its tenant ceiling for its tier.

fix • Reuse an existing tenant_id or upgrade the plan.

tier_restricted HTTP 403

The feature is not available on the current tier.

fix • Upgrade the plan, or drop the field that requires the higher tier.

sovereign_not_available HTTP 402

Sovereign mode requires the Sovereign add-on (Team plan).

fix • Add the Sovereign add-on in billing, or create the project without sovereign mode.

sovereign_addon_required HTTP 402

A write targeted a sovereign project without an active add-on.

fix • Re-activate the add-on, or move the memory to a non-sovereign project.

batch_budget_exhausted HTTP 422

A batch request exceeded the per-request item or byte budget.

fix • Split the batch into smaller requests.

> not found

project_not_found HTTP 404

No project with this ID exists in your account.

fix • List your projects and use an ID from that response. IDs are proj_-prefixed UUIDs.

memory_not_found HTTP 404

No memory with this ID exists in your account.

fix • The memory may have been deleted, or it belongs to another account. Deletion is a hard cascade — it does not come back.

no_project_found HTTP 400

The account has no project at all, and the call needs one.

fix • Create a project in the dashboard, or pass project_id explicitly.

project_id_required HTTP 400

The account has several projects, so the target is ambiguous.

fix • Pass project_id on the request. It is only optional for single-project accounts.

not_found HTTP 404

No erasure request exists for this memory.

fix • Check the memory ID, or open an erasure request first.

> conflict & immutability

decision_immutable HTTP 405

Decision memories cannot be edited in place — that is the point of the type.

fix • Use POST /v1/memories/{id}/supersede to record the change and keep the audit chain.

already_superseded HTTP 409

This memory has already been superseded by another.

fix • Follow the supersession chain to the current memory and supersede that one instead.

version_conflict HTTP 409

Another write landed between your read and your update.

fix • Re-read the memory, re-apply your change on the new version, and retry.

content_hash_conflict HTTP 409

The content changed since the hash you sent was computed.

fix • Re-read the memory and recompute the hash before promoting.

duplicate_content HTTP 409

An active memory with identical content already exists in this project and tenant.

fix • Deduplication is deliberate. Update the existing memory instead of adding a copy.

project_name_taken HTTP 409

A project with that name already exists in this account.

fix • Project names are unique per account. Pick another name, or reuse the existing project — list your projects to find its ID.

erasure_request_exists HTTP 409

A pending erasure request already exists for this memory.

fix • Wait for the pending request to complete, or cancel it first.

invalid_trust_state HTTP 422

The memory is not in a trust state that allows promotion.

fix • Only candidate memories can be promoted. Check trust_state before calling.

> request shape

validation_error HTTP 422

The request body failed validation.

fix • The details object lists every failing field. Fix them all — only the first appears in message.

invalid_idempotency_key HTTP 422

The Idempotency-Key header is longer than 255 characters.

fix • Use a UUID or any short unique string.

> billing integration

stripe_customer_missing HTTP 422

The account has no Stripe customer profile yet.

fix • Start a checkout once to create the profile, then retry.

checkout_unavailable HTTP 422

Stripe would not open a checkout session for this account.

fix • Usually a transient Stripe error. Retry; if it persists, contact support.

billing_portal_unavailable HTTP 422

Stripe would not open a billing portal session for this account.

fix • Usually a transient Stripe error. Retry; if it persists, contact support.

‹ 03 ›

code not listed here? it is either a transport-level failure (5xx) or new since this page was written — mail support@usememra.com with the X-Request-Id header from the response and we will trace it.

full api reference  •  python  •  typescript  •  php