Errors & limits

Error format

REST
MCP
CLI

A REST error has an HTTP status and a JSON body:

{
  "error": "rate_limited",
  "detail": "Too many write calls this minute.",
  "retryable": true,
  "request_id": "req_01JBY3K2Q8",
  "retry_after_ms": 12000
}

Retryable 429 and 503 answers also carry a Retry-After header.

An MCP tool error comes back as a normal JSON-RPC result with isError: true:

{
  "isError": true,
  "structuredContent": {
    "error": "Node fact_launch_date not found",
    "error_code": "not_found",
    "retryable": false
  }
}

Protocol problems — an unknown tool, invalid arguments — are JSON-RPC errors.

Every response carries the request’s id (x-request-id). Include it when you contact support.

Common error codes

Code	Status	Meaning	Retry?
`validation_failed`	400	An argument is missing, malformed or over a limit. The detail says which.	Fix the request
`unauthorized`	401	No credential, or it was rejected or revoked.	Sign in again
`graph_frozen`	401	The API key’s graph is read-only after a downgrade.	Upgrade or use another graph
plan limit (e.g. `document_limit_reached`)	402	A Free allowance is used up.	Upgrade (documents, meetings and notes also return next usage period)
`organization_write_mode_not_permitted`	403	Organization write mode is on, but you can no longer write the organization’s graph.	Turn write mode off
`not_found`, `start_node_not_found`	404	The node, edge or file doesn’t exist.	No
`node_exists`	409	`hm_store` with `if_exists: "error"` on an existing key.	No
`edge_version_conflict`	409	The edge changed since the `edge_version` you sent.	Re-read, then retry
`node_deleting`	409	The key is still being deleted in the background.	Yes, later
`idempotency_conflict`	409	The same `X-Request-ID` was reused with different input.	Use a new id
`file_quota_exceeded`	413	The file is over its type’s size limit.	No
`rate_limited`	429	Over your plan’s per-minute rate limit.	Yes, after `retry_after_ms`
`analysis_pending`	503	`hm_list_orphans` before the first graph analysis finished.	Yes, after `retry_after_ms`
`dependency_unavailable`, `transaction_conflict`	503	A temporary problem on HyperMemory’s side.	Yes, with backoff

Any answer with retryable: true is safe to retry. Retry writes with the same X-Request-ID so they are applied exactly once.

Rate limits

Tool calls are limited per account, per minute, in three buckets:

Bucket	Tools	Free	Basic	Pro	Business	Enterprise
Read	every tool not listed below	30	60	120	240	600
Write	`hm_store`, `hm_update`, `hm_forget`, `hm_add_relationships`	30	60	60	120	300
Ingest	`hm_ingest`, `hm_upload_file`	3	10	30	100	300

A 429 answer includes bucket, limit_per_minute and retry_after_ms.

Size limits

Item	Limit
MCP request body	64 MiB
REST request body	16 MiB (use `/upload-file` or the dashboard for files)
Node key	512 bytes
Node description	16 KiB (aim for 80–300 characters)
Node `data`	64 KiB
Node `search_text`	32 KiB
Relationships per `hm_store`	99
Relationships per `hm_add_relationships`	25
Hyperedge participants	2–256
`hm_recall` results	1–50
`hm_get_nodes` keys	1–50
`hm_find_related` nodes / depth	500 / 3
`hm_ingest` text	50,000 characters
`hm_timeline` entries per page	200
Timeline entry	16 KiB summary, 64 KiB `meta`
Uploaded file	50 MiB documents, 20 MiB images, 100 MiB audio; about 47 MiB through MCP

Monthly allowances — queries + nodes, documents, meetings — depend on your plan. See Plans.