Handling errors
Every Braize error is an RFC 9457 Problem Details object with a stable type URI — here is the shape and the type URIs that exist today.
Braize follows RFC 9457 (Problem Details for HTTP APIs) for every error, on every surface. There is no second, ad-hoc error shape hiding anywhere in the API.
The shape
Every error response is Content-Type: application/problem+json with:
{
"type": "https://braize.app/errors/quota-exceeded",
"title": "Plan quota exceeded",
"status": 429,
"detail": "The 'free' plan queries_month limit is reached (200/200). Upgrade your plan to continue.",
"instance": "/v1/query"
}| Field | Meaning |
|---|---|
type | A stable URI identifying the error condition. type URIs never change or get repurposed — additive-only, forever. Match on this, not on status or title text. |
title | Short, human-readable summary. Not for matching against. |
status | The HTTP status code, repeated in the body for clients that only look at the payload. |
detail | Optional, request-specific explanation. |
instance | Optional, the request path the error occurred on. |
Type URIs that exist today
type | Status | Meaning |
|---|---|---|
https://braize.app/errors/unauthorized | 401 | Missing, malformed, or invalid/revoked API key. |
https://braize.app/errors/invalid-request | 422 | The request body failed validation — e.g. an unknown model alias. |
https://braize.app/errors/quota-exceeded | 429 | A plan limit (queries/month, pages indexed) is reached. See Rate limits & quotas. |
https://braize.app/errors/generation-unavailable | 503 | The upstream generation provider is temporarily down. Carries a Retry-After header (seconds). Note: an embedding-provider outage is not an error — retrieval degrades to lexical-only and the normal 200 envelope sets meta.degraded: true instead. |
https://braize.app/errors/stream-failed | — | An SSE stream (see below) broke mid-response; sent as an error event, not an HTTP status. |
https://braize.app/errors/internal-error | 500 | An unhandled server error. |
New error conditions arrive as new type URIs, never by changing what an
existing one means — treat an unrecognized type as a generic error and
fall back to status.
Streaming errors (SSE)
When you call /v1/query with "stream": true, the response is
text/event-stream. Every event's data: payload matches the schema named
by its event: field: answer.delta → text fragments, answer.citation →
a citation attaching to an offset in the accumulated text, answer.done →
stream complete, error → an inline Problem-shaped payload. Clients must
skip unknown event names — new event types are additive forever. See the
API reference for the full event schemas.
The success envelope, for contrast
A successful response is never a bare object — it's always
{"data": {...}, "meta": {...}}. meta.request_id is worth logging on your
side for support requests; meta.braize_version is the contract date this
response was generated against.
Rate limits & quotas
The exact free-beta quota numbers (200 queries/month, 100 pages indexed), the warning threshold, and what a 429 looks like.
Setting up MCP
Connect Claude Code, VS Code, Codex, or Windsurf to your workspace's knowledge over MCP — the real per-workspace endpoint and OAuth 2.1 config.