Errors

Every error from https://console.nace.ai is a JSON body with one shape and an HTTP status that names the error class. For how to retry, see Errors and retries.

Error envelopeCopy Anchor Link

{
  "error": {
    "type": "invalid_request_error",
    "message": "questions.a.type: must be \"noul\", \"choice\", or \"score\"",
    "issues": [
      { "path": "questions.a.type", "message": "must be \"noul\", \"choice\", or \"score\"" }
    ]
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

Error typesCopy Anchor Link

Response headersCopy Anchor Link

Order of checksCopy Anchor Link

POST /v1/systemone runs these checks in order and stops at the first failure.

1. Kill switch. 529 overloaded.
2. API key. 401 authentication_error, then 402 payment_required or 402 insufficient_credit.
3. Rate limits. 429 rate_limit_error, or 529 overloaded for shared capacity.
4. Body parsing and validation. 422 invalid_request_error.
5. Model evaluation. 422 invalid_request_error for a request over the token limit, 529 overloaded when the model service does not answer.
6. Anything unexpected. 500 internal_error.

A request that reaches step 4 has already used a slot in the rate limiter, so a request that fails validation still counts toward the per-minute limit. See Limits.

GET /v1/models runs steps 1 and 2 only, and step 2 stops after the key check.

authentication_error (401)Copy Anchor Link

One message:

Invalid API key. Pass a nace_sk_ key as `Authorization: Bearer <key>`.

Returned by both endpoints when any of these is true:

• The Authorization header is missing.
• The header is not exactly Bearer followed by nace_sk_ and 43 URL-safe characters (A-Z, a-z, 0-9, _, -).
• The key does not exist.
• The key was revoked. A revoked key can keep working for up to 5 seconds on an instance that had it cached.

Real response, captured against production with no key:

HTTP/2 401
access-control-expose-headers: retry-after, retry-after-ms, x-request-id, x-typesafe-request-id
content-type: application/json
x-request-id: req_bd2dffad68f5f5fa4ce702e9bd516fb4
x-typesafe-request-id: req_bd2dffad68f5f5fa4ce702e9bd516fb4

{"error":{"type":"authentication_error","message":"Invalid API key. Pass a nace_sk_ key as `Authorization: Bearer <key>`."},"request_id":"req_bd2dffad68f5f5fa4ce702e9bd516fb4"}

The dashboard Playground uses the same type with its own message, Sign in to use the playground., when the browser session has ended.

insufficient_credit (402)Copy Anchor Link

One message:

This account has no spendable credit. Top up to keep going.

Returned by POST /v1/systemone when the account's spendable credit is zero and no card pays for usage beyond it. Spendable credit is the sum of what remains on grants that have not expired. Any positive amount admits the request, so the last request before the balance reaches zero still runs. An account with a saved card and auto-pay on is never refused for lack of credit. GET /v1/models does not check credit and keeps working. Top up or add a card on the dashboard Billing page. See Pricing.

payment_required (402)Copy Anchor Link

One message:

This account has an unpaid invoice. Pay it on the Billing page to keep going.

Returned by POST /v1/systemone, the Playground, and the document routes when a charge to the account's card failed, or an invoice is still unpaid at the end of the day it was issued. The account is paused: requests that spend credit are refused, and reads keep working, including GET /v1/models. The response is not retryable until the invoice is paid. Pay it with the Pay button on the dashboard Billing page. The pause lifts as soon as Stripe reports the invoice as paid. See Pricing.

invalid_request_error (422)Copy Anchor Link

error.message is the first issue, written as path: message, or the bare message when the path is empty. error.issues lists every problem the validator found in one pass. Paths are dotted: questions.<id>, questions.<id>.criteria.<key>, questions.<id>.criteria.<index>.

Every issue Drex itself produces:

Two more sources exist and are rare. If the model service rejects a request that passed every check above, Drex forwards the service's own validation messages as issues, or invalid request when the service's detail cannot be read. If the validator somehow finishes with no issue to report, error.message is Invalid request..

Example outputs, all real captures. Only request_id is illustrative.

A TypeSafe client that still sends its default model:

{
  "error": {
    "type": "invalid_request_error",
    "message": "model: unknown model \"jev-latest\"; use \"drex-v1.0\", \"drex-v1.5\" or \"drex-latest\"",
    "issues": [
      { "path": "model", "message": "unknown model \"jev-latest\"; use \"drex-v1.0\", \"drex-v1.5\" or \"drex-latest\"" }
    ]
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

One field, two issues. instructions was an object, which fails the type check and also leaves the noul question without instructions or criteria:

{
  "error": {
    "type": "invalid_request_error",
    "message": "questions.a.instructions: must be a string",
    "issues": [
      { "path": "questions.a.instructions", "message": "must be a string" },
      { "path": "questions.a.instructions", "message": "noul needs instructions or criteria" }
    ]
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

A state of about 230 KB sent to drex-v1.0, under the byte limit but over its row limit:

{
  "error": {
    "type": "invalid_request_error",
    "message": "Request too long: the state plus its longest question exceed the 32,768-token limit of drex-v1.0. Shorten the state or that question.",
    "issues": [
      { "path": "state", "message": "exceeds the 32,768-token limit" }
    ]
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

A state of about 1.2 MB, rejected before the model service sees it:

{
  "error": {
    "type": "invalid_request_error",
    "message": "request body must be at most 1048576 bytes",
    "issues": [
      { "path": "", "message": "request body must be at most 1048576 bytes" }
    ]
  },
  "request_id": "req_0123456789abcdef0123456789abcdef"
}

rate_limit_error (429)Copy Anchor Link

Two messages. Both carry retry-after and retry-after-ms.

The quotas per tier are in Limits. Both limits are per account, so every API key on the account and the dashboard Playground draw from the same counters.

overloaded (529)Copy Anchor Link

Three messages. All carry retry-after and retry-after-ms. None of them is caused by the request body, so the same request can succeed on retry.

The response never says which of these upstream conditions occurred and never includes the model service's status code or body. Drex logs that detail under the request_id.

internal_error (500)Copy Anchor Link

One message:

Something went wrong on our side.

An exception that no other branch handled. Retry once, then send the request_id to support@nace.ai. No credit is debited for a request that returns 500, or for any other error response.

Document routesCopy Anchor Link

The /v1/documents/* routes use the same envelope with two more fields, error.code (the exact cause) and error.retryable, and three more types: not_found_error (404, 410), conflict_error (409) and service_unavailable (503). The full table is in Perception errors.