Summary: Cortrix is open source semantic storage for AI agents. When a call fails, Cortrix returns an error with a fixed structure: an error code, whether it's worth retrying, an error category, and structured data for the fix. An agent doesn't have to understand the error text to decide whether to add a parameter and retry, switch to a key with more permission, hand the problem to a person, or give up. We wrote an agent that reads only those fields and ran it against 15 requests that fail. It got 9 right from the fields alone, and we walk through the other 6 below. We also checked each one by hand: not one needed the error text. This is part 4 of the Agent First Design series.

A parameter is missing. The key doesn't have enough permission. The request body is malformed. A feature isn't turned on. An agent calling storage can run into errors like these on any given day.

A person reads the error text and works out what to change. If all the agent gets back is plain text, it might retry the request exactly as it was, spinning on something that will never succeed. Or it might give up and hand a problem back to a person that one added parameter would have fixed. If the model is strong enough, it may well think its way to the right fix, but then the outcome depends on the model.

Errors from Cortrix: let the fields decide the next step

Cortrix error responses have a fixed structure. The API spec requires four fields: code, message, retryable, and category.

  • code: the error code. The agent branches on it.
  • retryable: whether sending the same request again can help.
  • category: the kind of error, with only five values: auth (permission), quota, transient (a temporary fault), permanent (it won't clear up on its own), and timeout.
  • structured_data: the data needed to fix the request, such as which parameter is missing.
  • message: an explanation for people. The spec says agents shouldn't parse it with regular expressions. Anything structured goes in structured_data.

This isn't only the main path. An uncaught exception comes back as JSON in the same structure, not as a plain-text 500.

What we measured: an agent that reads the fields and never the text

To check whether an agent can decide from these fields alone, we wrote one that follows fixed rules. It reads only code, retryable, category, retry_after_ms, and structured_data. It never reads message. From those it picks one of five actions: fix what's missing and retry, switch to a key with more permission, hand it to a person, give up, or retry as is. We ran it against a Cortrix server with authentication on and no large language model (LLM) configured, and we set up 15 requests that would fail.

Start with a common one: deleting a document and forgetting the namespace.

DELETE /documents/01M6NGQR5K4NHNW14AFZ5YP7KN
  400  CX_ERR_MISSING_PARAM  category=permanent  retryable=false
       structured_data={"missing_param": "namespace"}
agent: add query param namespace and retry -> 204

retryable=false tells the agent that sending the same request again is pointless, and structured_data names the missing parameter, namespace. The agent adds it, the retry works, and the agent never reads the error sentence.

Now two cases that need a different kind of handling:

POST /gc/restore  (agent key)
  403  FORBIDDEN  category=auth  retryable=false
agent: repeat with the admin key -> 200

POST /gc/purge  (no X-Ops-Confirm header)
  400  CX_ERR_OPS_CONFIRM_REQUIRED  category=permanent  retryable=false
agent: nothing sent, handed to a human

In the first, the key doesn't have enough permission. category=auth is the signal. The agent repeats the call with the admin key, and it works. The second is a destructive operation that needs an explicit confirmation. The error code already says "this needs confirmation," and the agent doesn't make that call for a person, so it hands the request over.

A request body that isn't valid JSON, creating a namespace that already exists, and calling memory extraction on a server with no LLM configured all return category=permanent and retryable=false. The agent gives up and reports, and doesn't spin on them.

15 errors grouped by the agent's decision: fix and retry 1, switch keys 5, ask a human 1, give up 6, all from fields alone; 4 wrong decisions on missing namespaces, 2 batch restore calls with too few fields to decide, 0 that needed the message
Figure 1: 15 errors, grouped by what the agent decided. ✓ decided right, ✗ decided wrong, ? not enough fields to decide.

Of the 15 failing requests that needed a decision, here's how it came out:

ResultCount
Decided correctly from the fields9
Decided wrongly from the fields4
Fields not enough to decide2
Needed to read the message text0

All 4 wrong decisions were requests to a namespace that doesn't exist. On the three endpoints we tested (reading a namespace, listing its documents, and querying), Cortrix returns the same 403, CX_ERR_NS_UNAUTHORIZED, for "doesn't exist" and "no permission," and the two errors look exactly the same. Our agent saw auth and reached for the admin key, but the name doesn't exist, so a different key can't help.

The 2 it couldn't decide were calls to the batch restore endpoint. It returns results per document with HTTP status 200, and the documents that failed sit in a failed list. An agent has to read that as a partial success and can't just check whether the outer response is an error. We cover how to handle both cases in the recommendations below.

The 0 in the last row of the table comes from checking each response by hand. Of the 15 responses, 13 had a message, and reading it wouldn't have turned a single decision into a right one. Of the 4 wrong calls, 3 had a message that was just the error code, and the fourth only said in general terms that some namespace wasn't authorized, while the name itself was already in structured_data. The 2 undecidable calls had no message in their failed entries at all.

Errors from vector databases: how Milvus, Qdrant, Pinecone, and Weaviate tell the caller

In Cortrix, whether to retry, what kind of error it is, and what data fixes it are all fields in the response, so an agent doesn't have to understand any text. We read the official docs, API specs, and server source for a few vector databases. Whether a retry makes sense mostly has to be read from the docs or the error text; structured signals show up only here and there:

  • Milvus: the gRPC (a remote procedure call framework) status message has a retriable boolean. Of what we read this time, it's the only field where the server hands back a yes-or-no answer on retrying. We didn't verify whether the REST API carries this field.
  • Qdrant: in the server source, a rate-limited response can carry a Retry-After header, but the official docs don't mention it.
  • Pinecone: which errors to retry and how to back off is written in prose in the docs. Retry 5xx and 429, don't retry other 4xx.
  • Weaviate: the HTTP API's general error body is a list of message entries; only a few errors, such as the 429 for a usage limit, carry a stable errorCode. The Model Context Protocol (MCP) server returns HTTP 200 with isError: true and a sentence of text when permissions or parameters are wrong.
The Status message in milvus-proto common.proto, with an orange line under bool retriable = 4
Figure 2: The retriable field of the Status message in proto/common.proto, milvus-proto v3.0.5, captured 2026-11-09. See reference [2]. The orange lines in the screenshots are ours.
Qdrant helpers.rs setting the Retry-After header on a rate-limited response, with an orange line under header::RETRY_AFTER
Figure 3: Qdrant v1.20.0, src/actix/helpers.rs, setting the Retry-After header when a request is rate limited, captured 2026-11-09. See reference [3].
The Implement retry logic section of the Pinecone docs, with an orange line under the sentence about retrying 5xx and 429
Figure 4: Retry guidance on the Pinecone "Error handling" page, captured 2026-11-09. See reference [4]. The marked sentence covers retrying 5xx and 429; "don't retry other 4xx" is in the retry best practices on the same page.
The Errors and limits section of the Weaviate MCP server docs, with an orange line under the sentence about HTTP 200 with isError: true
Figure 5: The "Errors and limits" section of the Weaviate MCP server docs, captured 2026-11-09. See reference [5].

That's only what we saw in the material we read. If we didn't see something, that doesn't mean the product doesn't have it. The materials we read are listed in the references at the end.

Advice for agents: category and retryable first, then structured data

  • Start with category and retryable to pick a direction. Don't retry a permanent error as is. For auth, check permissions first. For transient and timeout, wait a bit and try again when retryable=true.
  • When you need to fix the request, take the data from structured_data, such as the name of the missing parameter or the list of namespaces you have no permission for. Write message to the log and leave it for people.
  • On CX_ERR_NS_UNAUTHORIZED, first check that the namespace name is spelled right and the namespace exists, and only then try another key. On the endpoints we tested, "doesn't exist" and "no permission" are the same 403, and the admin key won't fix a misspelled name.
  • When you call batch restore (POST /gc/restore), don't stop at HTTP 200. Read coverage_ratio and failed. Every entry carries error_code, retryable, and category, so handle each one with the same rules above. It's the same partial success convention as in part 1 of this series.
  • For operations that need an explicit confirmation, like a purge, hand them to a person. Don't let the agent add the confirmation header itself.

Frequently asked questions

What fields does a Cortrix error response have?

Four are required: code, message, retryable, and category. On top of that, structured_data holds the data for the fix and retry_after_ms holds a suggested wait time (when it's missing, back off on your own schedule). Most errors also carry a request_id. category has only five values: auth, quota, transient, permanent, and timeout.

Does an agent need to parse the error message text?

No. Our agent reads only the fields, and across 15 failing requests it never needed the text. The API spec also says message is for people and agents shouldn't parse it with regular expressions.

Why do I get a 403 when the namespace name is wrong?

The three endpoints we ran (GET /namespaces/{name}, GET /namespaces/{name}/documents, and the query endpoint POST /query) return the same 403, CX_ERR_NS_UNAUTHORIZED, for both "doesn't exist" and "no permission." When an agent gets it, it should check the namespace name first and only then try another key.

How do I know which items failed when a batch restore partly fails?

Look at the failed list and coverage_ratio in the response. The HTTP status is 200, and every failed item carries error_code, retryable, and category.

Series navigation

We turned the decide-from-fields rules into an example in the Cortrix repo, at examples/error-handling. decide.py is about 70 lines you can copy into your own agent. demo.py sends six requests that fail on purpose and prints the fields, the decision, and the next step for each. Build and start Cortrix from main by following the instructions in that directory, and you can run it yourself. The runs in this post used v1.0.0-rc.2; on main, failed entries from batch restore carry more detail, so your output will differ a little:

python examples/error-handling/demo.py

If these errors save you a layer of error handling, we'd love it if you gave Cortrix a star on GitHub.

References

The commands and output in this post come from a build of Cortrix v1.0.0-rc.2 with authentication on and no LLM configured.