Skip to main content
CodeMeaningTypical fix
401Invalid or missing tokenAdd Authorization: Bearer … header
403RLS or scope deniedCheck org/agent/namespace; ensure key has access
409Idempotency conflictReuse the same Idempotency-Key and safely retry
422Validation errorMissing entity_id or fact fields (subject,predicate,object_*)
429Rate limitedBack off; use X-RateLimit-Remaining and X-RateLimit-Reset headers

​
Common mistakes

  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.