UnisonHow do I read Unison error responses?
Understand the Unison error envelope: every error is a JSON object with a snake_case code and a human-readable message.
My request failed. What does the error response look like?
Every Unison API error uses the same envelope format:
{
"error": {
"code": "snake_case_error_code",
"message": "Human-readable description of what went wrong."
}
}The HTTP status code tells you the category; the code field tells you the specific cause.
Common codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_request | Malformed JSON or a missing required field. |
| 401 | unauthorized | Missing or invalid Authorization header. |
| 403 | forbidden | Key doesn't have permission for this operation or path. |
| 404 | not_found | The page or resource doesn't exist. |
| 409 | conflict | Optimistic-concurrency conflict — re-read and retry. |
| 422 | unprocessable_entity | Request is syntactically valid but semantically wrong (e.g., invalid path format). |
| 429 | rate_limited | Too many requests — back off and retry. |
| 500 | internal_error | Something went wrong on Unison's side. Retry with exponential backoff. |
Handling errors in code
const res = await fetch('https://brain.unisonlabs.ai/v1/brain/context?q=foo', {
headers: { Authorization: `Bearer ${token}` },
});
if (!res.ok) {
const { error } = await res.json();
console.error(`[${error.code}] ${error.message}`);
}Branch on error.code for recoverable errors (429, 409, 500); surface the message for debugging.
See also: Handling 429s, Concurrency conflicts.
How do I correct a wrong fact in the brain?
Correct incorrect facts in Unison by writing the corrected version — the brain uses bitemporal supersession, so old facts are retired, not deleted.
How do I handle rate limit errors (429)?
Handle Unison 429 rate limit responses with exponential backoff and jitter to avoid thundering-herd retries.