| 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
- Blank agent + wrong namespace → no matches.
- Sending both
object_textandobject_entityfor a fact. - No
keys[]for singleton facts, so supersession never occurs. - Forgot
Idempotency-Keyon retries; server returns 409.