> ## Documentation Index
> Fetch the complete documentation index at: https://docs.flumes.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes & Troubleshooting

> Resolve issues fast and keep shipping.

| Code | Meaning | Typical fix |
| - | - | - |
| **401** | Invalid or missing token | Add `Authorization: Bearer …` header |
| **403** | RLS or scope denied | Check org/agent/namespace; ensure key has access |
| **409** | Idempotency conflict | Reuse the same `Idempotency-Key` and safely retry |
| **422** | Validation error | Missing `entity_id` or fact fields (`subject`,`predicate`,`object_*`) |
| **429** | Rate limited | Back off; use `X-RateLimit-Remaining` and `X-RateLimit-Reset` headers |

## Common mistakes

<Warning>
  1. Blank agent + wrong namespace → no matches.
  2. Sending both `object_text` and `object_entity` for a fact.
  3. No `keys[]` for singleton facts, so supersession never occurs.
  4. Forgot `Idempotency-Key` on retries; server returns 409.
</Warning>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.