Errors

The error shape, and what to do about each code.

A failed procedure returns an HTTP error status and a JSON body in the same json envelope as a success:

{
  "json": {
    "defined": false,
    "code": "BAD_REQUEST",
    "status": 400,
    "message": "Input validation failed",
    "data": { "issues": [ { "path": ["text"], "message": "Provide text or at least one attachment" } ] }
  }
}

Field	Use it for
code	Deciding what to do. Branch on this, not on message.
status	The HTTP status, repeated in the body.
message	A human-readable reason. Show it or log it; do not parse it.
data	Extra detail when present, such as the input fields that failed validation.

​

Codes

Code	Status	What it means	What to do
BAD_REQUEST	400	The input failed validation or makes no sense in the current state.	Fix the input. data.issues names the field when it is a validation error.
UNAUTHORIZED	401	No valid session.	Sign in again and retry with the new token.
FORBIDDEN	403	You are signed in but not allowed to do this, for example a member trying to invite people.	Ask a space owner or admin. Do not retry.
NOT_FOUND	404	The bot, chat or item does not exist in this space, or you cannot see it.	Check the id and the x-cadenceplus-space-id header.
CONFLICT	409	Someone else changed the thing first, for example an instruction file saved in another tab.	Fetch the latest version, reapply your change, and send it again.
PRECONDITION_FAILED	412	The server does not offer this, for example buying model credits on a server without managed models.	Do not retry.
TOO_MANY_REQUESTS	429	A provider (for example the computer host) is limiting requests.	Wait, then retry with backoff.
SERVICE_UNAVAILABLE	503	A provider is down or slow, such as a computer that did not start in time.	Retry with backoff.
BAD_GATEWAY	502	An upstream service returned something unusable.	Retry with backoff.
INTERNAL_SERVER_ERROR	500	An unexpected failure.	Retry once. If it repeats, report it with the time of the request.

​

Conflicts and expected values

Several procedures take an “expected” value so two people editing the same thing do not overwrite each other:

• bots/update takes expectedInstructions.
• botFiles/update takes expectedContent.
• memory/update takes expectedRevision.

Send the value you started from. If it no longer matches, you get CONFLICT instead of a silent overwrite.

​

Retrying safely

Some procedures take a clientNonce (for example threads/send and artifacts/create). Use one random value per logical action and reuse it on retries. A retry with the same nonce does not create a second message or upload.