Errors

Cortex returns small, typed JSON error shapes from platform-wide handlers, not a single envelope for everything. This page lists the ones you will actually hit and what each status means.

Reading the status

Status	Meaning	What to do
400	Validation or malformed body	Fix the request. The body names the offending field.
401	Missing or invalid token	Get a fresh token.
403	Authenticated, but your permissions do not allow it	You lack the required domain:action.
409	Concurrency conflict (optimistic lock)	The record changed under you. Re-read and re-apply.
423	Locked: the business day is closing	Retriable. Wait for end-of-day to finish, then retry.
5xx	Our fault	Retry idempotently; if it persists, quote the correlation id.

The shapes

Validation (400) names the first offending field and, where relevant, a per-field map:

{
  "error": "validation",
  "message": "amount.currency: must be a valid ISO 4217 code",
  "fieldErrors": { "amount.currency": "must be a valid ISO 4217 code" }
}

Conflict (409) means a concurrent write changed the record after you read it:

{
  "error": "conflict",
  "message": "the record was changed by someone else; re-read and try again"
}

Locked (423) means the input window is closed while the business date rolls:

{ "error": "InputWindowClosedException", "message": "business date is closing; retry shortly" }

The correlation id

Every request and response carries an X-Correlation-Id header. If you send one, Cortex honours it (when safe) and echoes it back; otherwise it generates one. It is written to the server logs, so quote the X-Correlation-Id value when raising a support ticket. It is the fastest way to find your request.

The correlation id is a header, not a body field

It is not inside the error JSON. Read it from the response headers.

202 is not an error

A write that needs authorisation returns 202 Accepted with an approvalId. The command was accepted and parked for a checker, not rejected. See Maker-checker over the API.

Agent gateway errors

The AI agent gateway uses its own typed error code set over JSON-RPC: FORBIDDEN, LIMIT_EXCEEDED, VALIDATION_FAILED, NOT_FOUND, IDEMPOTENCY_CONFLICT, PREVIEW_EXPIRED, STEP_UP_REQUIRED, COMPLIANCE_HOLD. These are distinct from the REST status codes above.