Skip to main content
HTTP errors commonly contain an error string. Some endpoints add code, details, or retry information; there is no universal requestId or error envelope. MCP tools may instead return text content with isError: true.

​
IDs, methods, and bodies

Memory and KB IDs are Convex IDs, not UUIDs. Copy IDs returned by the service. Recall uses POST; health supports GET and POST. HEAD is not a universal authenticated probe.
The shared 429 body is {"error":"Rate limit exceeded."} with Retry-After, limit, remaining, and scope headers. Some routes use older responses; do not require identical error shapes across the API.

​
Content and provider errors

Update and supersede return HTTP 409 with error: "redacted_content_write", plus fields and message, when a redaction placeholder would overwrite a secret-bearing stored field. Restore the intended content, or explicitly set allowRedactedContent: true if replacing it with the placeholder is deliberate. Content screening checks prompt injection, exfiltration, role hijacking, invisible Unicode, and encoded payloads. It is not a general violence or copyright classifier. A blocked memory write returns HTTP 400 with {"error":"Memory blocked: <reason> [<threatId>]"}. For example:
Review the reason and threat identifier, then remove the flagged instructions or payload before retrying. Embedding and distillation use the owner’s configured OpenRouter credentials on the hosted backend. Check the owner’s settings when a provider is unavailable; a generic Gemini-key change is not the remedy for every failure. Retrieval can also return a successful but degraded result, so inspect degraded, degradation, and diagnostics where present. KB stable keys support upserts; duplicate content is not universally an error. Chunk metadata and titles are optional. A usable import body is:
Do not assume a universal 10,000-chunk HTTP import limit or that a failed import rolled back earlier chunks. See KB imports.

​
Named error codes

Not every endpoint returns code. Read the HTTP status and error text as well.

​
Debugging checklist

  1. Confirm the HTTP method and URL in the endpoint map.
  2. Check the Bearer credential with an authenticated health request.
  3. Parse your JSON locally and verify required fields, types, and returned IDs.
  4. Reproduce with the smallest useful request in the same account and scope.
  5. Inspect status, response body, and Retry-After. Preserve a request ID when the endpoint supplies one; it is not universal.
  6. For an import interruption or write timeout, inspect saved state before retrying.
Content-screening failures identify suspicious instructions or payloads. Review the flagged material and any supplied threat identifier. Do not disguise blocked instructions to force them through. A count mismatch between stats and recall is not proof of blocking: stats is account-wide and recall is bounded and scoped. For help, send support a minimal request with credentials and private content removed, the endpoint, status, response, and approximate time. Include a request ID only if one was returned.