Error Codes

Fresh

HTTP Status Codes

Code	Error	Description	Solution
200	Success	Request completed	—
400	Bad Request	Invalid parameters	Check request body and parameters
401	Unauthorized	Invalid or expired API key	Verify API key, regenerate if needed
402	Payment Required	Insufficient credits	Add credits to your account
403	Forbidden	Insufficient permissions or bank scope	Check key permissions and bank scope
404	Not Found	Resource does not exist	Verify bank_id, memory_id, or mental_model_id
500	Server Error	Internal server error	Retry, contact support if persistent

Common Error Responses

401 Unauthorized

{
  "detail": "Invalid or expired API key"
}

404 Not Found

{
  "detail": "Bank with ID 'invalid-bank' not found"
}

400 Bad Request

{
  "detail": "Validation error: items is required"
}

402 Payment Required

{
  "detail": "Insufficient credits to complete this operation"
}

Troubleshooting by Operation

Retain Errors

Error	Cause	Fix
400	Empty content	Provide non-empty content string
400	Missing items array	Include items array in body
402	No credits	Add credits on Billing page
404	Invalid bank_id	Create the bank first or verify bank exists

Recall Errors

Error	Cause	Fix
400	Empty query	Provide a search query string
400	Invalid types filter	Use valid types: world_fact, experience, observation

Reflect Errors

Error	Cause	Fix
400	Empty query	Provide a question string
400	Invalid response_schema	Verify JSON Schema is valid

Mental Model Errors

Error	Cause	Fix
400	Missing name or source_query	Both fields are required
404	Invalid mental_model_id	Verify the model exists

MCP Errors

Issue	Solution
0 tools discovered	Auth failed silently — re-add MCP server
OAuth page does not open	Check Node.js installed, verify URL
Tools appear but fail	Check credits and bank name validity