Error Playbook

Common integration failures and fast fixes.

Prerequisites

• Access to request and response logs
• Endpoint and payload details for failing calls
• Current API field usage (external_user_id, memory_policy)

Minimal Setup

1. Identify the failing endpoint and status code.
2. Compare payload shape with Request Templates.
3. Apply the matching fix from this playbook.

401 Unauthorized

Symptoms

• API calls fail with auth errors across endpoints.

Fix

• Ensure one auth method is set: X-API-Key, Authorization: Bearer, or session token.
• Verify key/environment in runtime context.

422 Validation Error

Symptoms

• Request rejected due to schema mismatch.

Fix

• Check required fields for that endpoint.
• Validate JSON shape against request templates.
• Remove deprecated fields that conflict with current schema.

Search Returns Weak or Empty Results

Symptoms

• Missing relevant memories.

Fix

• Set enable_agentic_graph=true.
• Raise max_memories and max_nodes.
• Improve query specificity.
• Confirm scope fields (external_user_id, organization_id, namespace_id).

Structured Data Not Appearing in Graph

Symptoms

• Nodes/edges not materializing as expected.

Fix

• Use memory_policy.mode="manual" for strict control.
• Verify nodes and relationships IDs/types.
• If using auto mode + constraints, verify node and edge constraints actually match extracted entities.

Messages Stored But Not Becoming Memories

Symptoms

• Session history works, search misses expected facts.

Fix

• Ensure process_messages=true.
• Validate role/content payload.
• Check processing status fields in message responses.

Document Upload Stalls

Symptoms

• upload_id exists but status remains pending.

Fix

• Poll GET /v1/document/status/{upload_id}.
• Verify file size/type and provider fallback constraints.
• Retry upload with reduced file size if needed.

Multi-Tenant Data Leakage Risk

Symptoms

• Ambiguous cross-tenant retrieval behavior.

Fix

• Set organization_id and/or namespace_id on writes and searches.
• Use memory_policy.acl for explicit read/write boundaries.
• Do not rely on implicit defaults for sensitive workloads.

Validation Checklist

• Auth method is configured exactly once
• Payload schema matches endpoint requirements
• Tenant scope and ACL settings are explicitly defined

Troubleshooting

If issues persist, run through Deprecations and Migrations to remove legacy fields, then retest with minimal payloads.