Errors - Cadence

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.