Reference

Errors, retries, and API conventions

Treat status codes as part of the contract. Retrying every failure blindly can duplicate work or overwrite a collaborator's changes.

Status codes

Status	Meaning	Agent action
`400`	Invalid route parameter, body, query, or contract.	Read the structured message/issues and fix the request. Do not retry unchanged.
`401`	Missing, invalid, revoked, or expired credential.	Replace/refresh the credential; never log it.
`403`	Credential is valid but lacks project/product/action authority.	Inspect `/api/auth/context` and request the minimum required grant.
`404`	Resource is absent or deliberately hidden by tenant isolation.	Verify IDs and current project context.
`409`	Optimistic concurrency or uniqueness conflict.	Reload, merge, and retry with the new expected version/revision.
`413`	Payload exceeds a configured limit.	Reduce payload size; OpenAPI raw specs are limited to 2 MB.
`429`	Rate limit reached.	Back off and honor `Retry-After` when present.
`5xx`	Server or upstream failure.	Retry safe/idempotent calls with exponential backoff and jitter.

Cursor pagination

GET /api/board/projects/<projectId>/work-items?limit=50&cursor=<last-id>

{
  "workItems": [ … ],
  "nextCursor": "<uuid-or-null>"
}

Continue until nextCursor is null. Do not derive cursors from array positions.

Optimistic concurrency

TDocs updates send expectedVersion.
TSwagger publication sends expectedRevisionNumber.
TSwagger rollback sends both target and expected current revision numbers.

Idempotency

Runs, usage, evidence, and events accept stable idempotency keys. Reuse the same key when retrying the same logical write:

terminal:<device-id>:<local-entity-id>:<action>

terminal:device-1:run-42:create
terminal:device-1:run-42:usage:final
terminal:device-1:run-42:evidence:tests

Dates and identifiers

Timestamps are ISO 8601 UTC strings.
Resource identifiers are UUIDs unless documented otherwise.
Money values use decimal USD fields; token counts are integers.
Optional fields should be omitted unless intentionally cleared with a documented null.

Safe retry rule

GET requests are safe to retry. Retry writes only when they are idempotent by contract or carry a stable idempotency key. For ambiguous network failures, read the resource before deciding whether to repeat the mutation.