examples · errors

Error responses

19 canonical errors, one per page. Every error response from the OriginChain API uses the same JSON shape:

{
  "error": "code",          // short machine-readable string
  "message": "human",       // plain-English explanation
  "retry": false            // true if the same request might succeed later
}

Some errors carry extra typed fields - purchase_url on a 402, retry_after_seconds on a 429, current_version on an OCC 409, trace_id on a 500. The individual pages show those.

400 - bad request

The request reached the server, parsed, and was rejected before the engine ran it. Fix the request and resend.

400 - malformed JSON body

The request body failed to parse as JSON. Trailing comma, unterminated string, wrong content-type.

→ 2

400 - unknown table (schema_not_found via SQL)

The SQL referenced a table that is not declared in any schema for this tenant.

→ 3

400 - unknown column in SELECT/WHERE

The translator could not resolve a column reference against the table's manifest.

→ 4

400 - column type mismatch on write

A value did not match the column's declared type. String into a float column, etc.

→ 5

400 - invalid vector mode (only fast / high_recall)

The topk mode field has only two legal values. Anything else returns 400.

→

401 / 402 / 403 - auth, billing, permission

The request was authenticated or authorised incorrectly, or it asks for a paid feature the tenant hasn't enabled.

401 - missing Authorization header

No Authorization header was sent at all. The router rejects before reaching the handler.

→ 7

401 - malformed bearer token

The header was present but did not parse as 'Bearer <token>'.

→ 8

401 - token revoked or expired

The token parsed but has been revoked from the admin console or is past its expiry.

→ 9

402 - addon required (paid feature)

The endpoint is gated by an addon the tenant has not enabled. Body carries a purchase_url.

→ 10

403 - token valid but for a different instance

The bearer is well-formed and not expired, but it does not authorise this tenant or instance.

→

404 - not found

The hostname, path, or resource id does not exist.

404 - instance / endpoint not found

The hostname or path did not match any provisioned instance or route.

→ 12

404 - schema not registered

The schema id in the URL is not registered for this tenant.

→

409 - conflict

The request is valid but conflicts with current state - a concurrent writer, or an already-enabled addon.

409 - optimistic-concurrency conflict on row write

A versioned write lost the race. Default writes are last-writer-wins; OCC is opt-in via If-Match.

→ 14

409 - addon already enabled

The addon-enable request hit a tenant where that addon is already on.

→

413 - payload too large

The body exceeded the per-call size cap of 8 MiB.

413 - payload over 8 MiB

The request body exceeded the per-call size limit. Split into smaller batches.

→

422 - semantically invalid

The request parsed but failed a higher-level semantic check.

422 - semantically invalid manifest (FK target missing)

The manifest parsed as TOML but failed semantic validation. FK targets a column that doesn't exist.

→

429 - rate limited

Per-API-key quota exceeded. See /docs/rate-limits for the full reference.

429 - rate limited (per-token cap)

The per-API-key request quota was exceeded. Honour the Retry-After header before retrying.

→

5xx - server-side

The server hit an unexpected condition or the engine was momentarily unreachable.

500 - internal server error

An unexpected server error. Trace id is included in the response; share it with support.

→ 19

502 - engine unreachable (failover in progress)

The control plane could not reach the tenant's engine. Usually transient; SDKs auto-retry.

→