How 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

The codes below are the ones a client should actually handle; other 4xx/5xx responses follow the same envelope.

HTTP	`code`	Meaning
400	`invalid_path`	Malformed path, or path not ending in `.md`.
400	`invalid_json`	Request body is not valid JSON.
400	`invalid_request`	Auth endpoints: missing or invalid field.
401	`unauthenticated`	Missing or invalid `usk_` token.
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.
413	`payload_too_large`	Request body exceeds the size limit.
429	`rate_limited`	Too many requests — back off and retry.
500	`rest_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.

How do I read Unison error responses?

Common codes

Handling errors in code

On this page