> ## 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>