Troubleshooting

This is expected behavior. After calling /v1/ingest, the event is queued for async enrichment which takes 1–5 seconds. During this window, the event's derived data (facts, embeddings) is not yet available for recall.

Solution: Wait a few seconds before calling recall, or design your flow so recall happens on the next user interaction (which naturally provides enough time).

The API key in your Authorization header is invalid, revoked, or malformed.

Checklist:

• Verify the key starts with cmk_
• Check for leading/trailing whitespace
• Confirm the key hasn't been revoked in the console
• Ensure the header format is: Authorization: Bearer YOUR_KEY

The type field must be one of: message, tool_call, or app_event.

Common mistakes:

• Using old type names like “fact”, “loop”, “episode”, or “chunk”
• Using uppercase: “Message” instead of “message”
• Missing the type field entirely

The token_budget must be between 200 and 8000 (inclusive).

Fix: Adjust your token_budget to be within the valid range.

// Valid ranges
{ "token_budget": 200 }   // Minimum
{ "token_budget": 2000 }  // Recommended
{ "token_budget": 8000 }  // Maximum

You've exceeded your plan's quota for the current billing cycle.

The response includes:

{
  "error": "quota_exceeded",
  "message": "Monthly ingest limit exceeded",
  "reset_date": "2026-03-01T00:00:00Z"
}

Options:

• Wait for the quota to reset (see reset_date in the response)
• Upgrade your plan for higher limits
• Check your project's Usage & Limits tab to see what's consuming quota

The Test Connection feature checks /healthz and /readyz on your CLAIV Memory backend.

Common causes:

• Backend is not running or not reachable
• CLAIV_MEMORY_API_BASE_URL is incorrect
• Network/firewall blocking the connection
• /readyz fails when PostgreSQL or Redis is down

CLAIV detected that this event is a duplicate of an existing event for the same user. The event_id is still returned, but no new enrichment is triggered.

This is normal behavior. Deduplication prevents unnecessary work when the same event is sent multiple times (e.g., retries).

Recall latency depends on the amount of stored data and the complexity of the query.

Optimization tips:

• Use lower token_budget values when you don't need extensive context
• Use thread_id to narrow the search scope
• Check the endpoint breakdown in Usage for latency trends