5.11 Error codes ¶

Every error payload has the shape:

{
  "ok": false,
  "error": {
    "code": "INVALID_INPUT",
    "message": "The text field is required."
  }
}

The full vocabulary:

INVALID_INPUT

Missing required field, wrong type, out-of-range value, malformed timestamp, etc.

AUTH_REQUIRED

No Authorization header was sent (HTTP 401).

AUTH_FAILED

Authorization header was present but the token didn’t match (HTTP 401). The server does not distinguish “missing” from “wrong” in error text; both surface as 401 at the protocol level.

NOT_FOUND

The requested id doesn’t exist.

SECRET_REJECTED

The submitted text matched the secret-shape detector (API key, private key, JWT, etc.).

LIMIT_EXCEEDED

A pagination or batch parameter exceeded its hard cap.

EMBEDDING_ERROR

The embedding provider returned an error or didn’t respond. Includes the provider’s status code and message in error.detail when available.

DATABASE_ERROR

PostgreSQL returned an error or the connection failed.

INTERNAL_ERROR

Catch-all for unexpected conditions. The server logs the full exception; the response carries only the generic message to avoid leaking implementation detail.