Skip to content

Error codes

The structure of an error response, the error categories, and common error codes.

Cortrix error responses are designed for programs and agents. Whether to retry, how long to wait, and what kind of error it is each have a dedicated field, so you never need to parse the message text.

Error response structure

{
  "error": {
    "code": "CX_ERR_DEPRECATED_FIELD",
    "message": "Field 'namespace' is deprecated, use 'namespaces' array instead",
    "retryable": false,
    "category": "permanent",
    "retry_after_ms": null,
    "structured_data": {
      "deprecated_field": "namespace",
      "use_instead": "namespaces"
    }
  }
}
FieldTypeDescription
codestringThe error code
messagestringA description for people. Don’t parse it in code. The structured details are in structured_data
retryablebooleanWhether a retry is worthwhile
categorystringThe error category. See the next table
retry_after_msinteger or nullThe suggested wait before a retry, in milliseconds
structured_dataobjectStructured data about this error, for programs to use
request_idstringA server-generated request identifier for finding the request in logs. Some error responses include it

Error categories

categoryMeaningWhat to do
authAn authentication or permission problemDon’t retry. Check your credentials or permissions
quotaA quota was exceededSlow down, or wait and try again
transientA temporary failureWait for retry_after_ms, then retry
timeoutA timeoutWait for retry_after_ms, then retry
permanentSomething is wrong with the request itselfDon’t retry it unchanged. Fix the request

Decide whether to retry

  1. Look at retryable first. If it’s false, don’t retry.
  2. For the wait time, use retry_after_ms, then the Retry-After header (in seconds), then exponential backoff.

The Python SDK has this logic built in. See Python SDK.

Partial success

Some operations return HTTP 200 even when part of the work failed. The details are in the response’s meta, and every failure carries the same structured fields:

OperationWhere the failures are
Cross-namespace querymeta.namespaces_failed[]
Batch document submitmeta.failed[]

When an asynchronous task fails, the failure appears in the task progress as error_code and error_msg, not in the response to the request that submitted it.

So don’t judge whether an operation fully succeeded from the HTTP status code alone.

How error codes are named

The spec requires every error code to use the CX_ERR_ prefix, which lets you filter Cortrix errors in logs and monitoring.

Note

In testing, some errors in v1.0.0-rc.2 used generic codes without the prefix, such as INVALID_ARGUMENT and NOT_FOUND. When you handle errors, go by retryable and category, and don’t assume every code starts with CX_ERR_.

Common error codes

These are the high-frequency codes registered in the spec, with the suggested way to handle each:

Error codeRetryableCategoryTypical causeWhat to do
CX_ERR_NAMESPACE_NOT_FOUNDNopermanentThe namespace name is misspelled, or the namespace was deletedConfirm the name with GET /namespaces, or create the namespace
CX_ERR_NS_UNAUTHORIZEDNoauthThe API key has no access to this namespaceRead the namespaces you can’t access from structured_data.unauthorized_namespaces and query only the ones you can
CX_ERR_NS_TIMEOUTYestimeoutA query on one namespace timed outUse the partial results you got, and optionally retry just that namespace
CX_ERR_RATE_LIMITYestransientThe rate limit was exceeded. The v1.0.0-rc.2 server doesn’t emit this codeWait for retry_after_ms and retry, or lower your request rate
CX_ERR_AUTH_INVALID_API_KEYNoauthThe API key is invalid or revokedUse a different API key
CX_ERR_INDEX_CORRUPTNopermanentThe vector index is unavailableUse the partial results and notify whoever operates the service

These are the error codes that came up in testing for this documentation:

Error codeHTTP statusWhen it appears
CX_ERR_DEPRECATED_FIELD400A query request used the singular namespace
CX_ERR_NS_NOT_FOUND404A file was uploaded to a namespace that doesn’t exist
CX_ERR_ADMIN_LOOPBACK_REQUIRED403An admin endpoint was called from a non-loopback address
CX_ERR_DISK_FULL507A file was uploaded while the data disk was at least 90% full. See Troubleshooting
CX_ERR_SPC_PROCESS_FAILED—An asynchronous processing task failed. It appears in the task progress

For the MCP adapter’s own error codes, see MCP server.

Agent hints in the OpenAPI spec

The OpenAPI spec annotates every endpoint with a set of x-cortrix-* extension fields, so an agent knows what kind of endpoint it’s dealing with before it calls it:

FieldMeaning
x-cortrix-retryableWhether this endpoint can usually be retried
x-cortrix-retry-strategyThe suggested way to retry: exponential_backoff, linear, no_retry, or immediate
x-cortrix-side-effectsThe side-effect category: none, read_only, write, or destructive
x-cortrix-auth-requiredWhether authentication is required
x-cortrix-auth-scopeThe required scope: ns:read, ns:write, tenant:admin, or ops:admin
x-cortrix-rate-limitThe rate limit, as count/period/scope
x-cortrix-typical-latencyEstimated P50 and P99 latency

These fields are design annotations in the spec, not measured results.

Next steps

Table reader