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), andtimeout.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 instructured_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.

Of the 15 failing requests that needed a decision, here's how it came out:
| Result | Count |
|---|---|
| Decided correctly from the fields | 9 |
| Decided wrongly from the fields | 4 |
| Fields not enough to decide | 2 |
Needed to read the message text | 0 |
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
retriableboolean. 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-Afterheader, 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
messageentries; only a few errors, such as the 429 for a usage limit, carry a stableerrorCode. The Model Context Protocol (MCP) server returns HTTP 200 withisError: trueand a sentence of text when permissions or parameters are wrong.

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.
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].

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
categoryandretryableto pick a direction. Don't retry apermanenterror as is. Forauth, check permissions first. Fortransientandtimeout, wait a bit and try again whenretryable=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. Writemessageto 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. Readcoverage_ratioandfailed. Every entry carrieserror_code,retryable, andcategory, 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
- Part 1: HTTP 200 Doesn't Mean You Got Everything. When a query only covers part of the data, the storage has to say what's missing.
- Part 2: kill -9 Halfway Through a Write, and the Data Lines Up Again After Restart. If a crash interrupts a write, the storage cleans up the half-written data on its own.
- Part 3: Getting a Deleted Doc Back Is as Easy as "Ctrl+Z". An agent deleted a document, and you can get it back by ID within 30 days.
- Part 4 is this post: when a call fails, the error should tell the agent what to do next.
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
- [1] Cortrix API spec, error responses: https://github.com/cortrix/cortrix/blob/v1.0.0-rc.2/api/components/errors.yaml
- [2] Milvus, milvus-proto
v3.0.5,proto/common.proto: https://github.com/milvus-io/milvus-proto/blob/2f00c7cf17db3ab3bb7b93ea8f2a7261bcc264da/proto/common.proto#L116-L123 - [3] Qdrant
v1.20.0,src/actix/helpers.rs: https://github.com/qdrant/qdrant/blob/222b2e44ab1c3f17e8246396ead6558e45041df7/src/actix/helpers.rs#L207-L224 - [4] Pinecone Docs, Error handling (accessed 2026-11-09, page undated): https://docs.pinecone.io/guides/production/error-handling
- [5] Weaviate Docs, MCP server (accessed 2026-11-09, page undated): https://docs.weaviate.io/weaviate/configuration/mcp-server
- [6] Weaviate
v1.40.4,openapi-specs/schema.json: https://github.com/weaviate/weaviate/blob/aa98b24f66096f916bbe79bd7923f7af13d5611d/openapi-specs/schema.json#L634-L650, https://github.com/weaviate/weaviate/blob/aa98b24f66096f916bbe79bd7923f7af13d5611d/openapi-specs/schema.json#L765-L796 - [7] Cortrix on GitHub: https://github.com/cortrix/cortrix
- [8] Example code for this post, examples/error-handling: https://github.com/cortrix/cortrix/tree/main/examples/error-handling
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.