Errors

Errors returned by the Drex application at https://console.nace.ai are JSON bodies with one shape and an HTTP status that names the error class. The hosting layer can reject an oversized HTTP body with a plain-text 413 Request Entity Too Large before Drex runs, without this JSON envelope. Keep inline images within the 4 MiB request-body limit, including base64 expansion; upload larger images and send their file references. For how to retry, see Errors and retries. The SDKs raise one error class per status; see Python and TypeScript.

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

No /v1 route sends Access-Control-Allow-Origin, so a page on another origin can't call Drex: call it from your server.

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 when the model pool is full.
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
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 insufficient available funds. Add funds to keep going.

Returned when free or prepaid funds cannot cover the request’s budget, including when other running work has reserved the available balance. Funds are reserved before provider execution. A request whose funding expires or runs out is cancelled free. An account with a saved card and auto-pay on is never refused for lack of funds. GET /v1/models does not check the balance and keeps working. Top up, or add a card and turn on pay as you go, 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 funds 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. A token-limit refusal is the exception: its message starts Request too long: and names the limit and the model. 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..

The following model-error response is illustrative: it shows the suffix when Drex 2.0 is the only publicly available active version. The actual public model ids and aliases after use depend on the environment. The other examples are real captures with illustrative request_id values.

A TypeSafe client that still sends its default model:

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

One field, two issues. A noul question's only criterion, criteria.true, was a number, which fails the type check and also leaves the question without instructions or criteria:

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

A short state with a question that puts the row over 262,144 tokens on drex-v2.0, while the JSON body remains under the byte limit:

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

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

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

Image errorsCopy Anchor Link

Only Drex Max reads images. For requests that reach Drex, these checks run with the others above, before its serialized-body check. The hosting layer may refuse an oversized HTTP body first with 413, so the 422 image errors below are not guaranteed for oversized inline images. The Drex Max allows options limit applies to every request to a served Drex Max model, with or without images:

After those checks pass, Drex reads each image. One it can't use fails the request with a single issue at images.<index> and the message Image could not be read. Use an accessible, valid still PNG/JPEG/WebP, at most 16 MiB and 40 megapixels; all images together must be at most 32 MiB. That covers a corrupt or animated image, another format, an image over a limit, and a workspace_file that you didn't upload without a workspace or that can't be found.

Multipart upload errorsCopy Anchor Link

A multipart/form-data request to POST /v1/systemone is read into the same body as a JSON request before any check above runs, so every error above applies to it too, with the paths of the equivalent JSON body (images.<index>, not assets). These checks run first. The first four rows stop the request at once with that one issue, because nothing after them can be checked without a readable request part. Every other row is collected in one pass over the form, so a request with several of those problems gets all of them in error.issues, the assets issues in the order the assets are listed and the <part> issues in the order the parts were sent. A part that an asset names is never also reported as unnamed, whatever else is wrong with that asset.

rate_limit_error (429)Copy Anchor Link

Three messages. All carry retry-after and retry-after-ms.

The quotas per tier are in Limits. The first two 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, and three more for Drex Max image requests. 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. Nothing is charged for a request that returns 500, or for any other error response.