Error responses
Match the HTTP status and error code to a recipe below. The response message explains the specific failure; optional fields may provide a retry delay, current row version or trace ID.
The example error envelope is:
{
"error": "code", // short machine-readable string
"message": "human", // plain-English explanation
"retry": false // true if the same request might succeed later
}Correct invalid requests before resending them. For server or connection failures, retry reads with bounded backoff. Check the outcome of a write before repeating it.
These failing-request snippets retain their original explicit tenant route. Use your deployment’s connection details and never print a token while diagnosing a failure.
- Read status and codeFind the matching error recipe.
- Identify the causeSeparate invalid input, access problems and temporary failures.
- Check uncertain writesRead the stored state before repeating a write.
- Correct and verifyApply the documented fix and check the result.
400 - bad request
The request is invalid. The problem may be JSON syntax, a name the schema cannot resolve, a type mismatch or an unsupported option. Correct the reported field before resending.
400 - malformed JSON body — The request body failed to parse as JSON. Trailing comma, unterminated string, wrong content-type.
400 - unknown table (schema_not_found via SQL) — The SQL referenced a table that is not declared in any schema for this tenant.
400 - unknown column in SELECT/WHERE — The translator could not resolve a column reference against the table's manifest.
400 - column type mismatch on write — A value did not match the column's declared type. String into a float column, etc.
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
Check whether the credential is missing, malformed, expired or insufficient. A capability that is not enabled has a separate response; inspect current configuration and billing before changing it.
401 - missing Authorization header — No Authorization header was sent at all. The router rejects before reaching the handler.
401 - malformed bearer token — The header was present but did not parse as 'Bearer <token>'.
401 - token revoked or expired — The token parsed but has been revoked from the admin console or is past its expiry.
402 - addon required (paid feature) — The endpoint is gated by an addon the tenant has not enabled. Body carries a purchase_url.
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.
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.
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 limit for that endpoint or gateway. Check row request limits before choosing a batch size.
413 - request body too large — 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
The configured request budget was exceeded. Read the retry delay and rate-limit guidance before sending more work.
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.
502 - engine unreachable (failover in progress) — The service could not reach the engine. Retry reads within a limit and reconcile uncertain writes before repeating them.