Decision API Docs

Error Reference for fail-closed integrations.

Decide sits before state-changing software actions. When the API cannot return a valid Decision Record, the caller should not silently approve. Route to review, hold the source record, or retry only when your integration policy explicitly allows it.

Back to docs Endpoint reference SDK status Readiness endpoint

Core Decision API errors

These errors apply to POST /api/decide. The safest default for irreversible actions is review, not approval.

Code	Status	Meaning	Caller behavior
`DECIDE_API_UNAUTHORIZED`	`401` / `403`	Missing, invalid, disabled, or out-of-scope production API key.	Do not execute. Fix server-side key configuration or account scope before retrying.
`DECIDE_API_RATE_LIMITED`	`429`	Request rate exceeded for the API key.	Honor `Retry-After` and `X-RateLimit-*`. Keep irreversible actions in review until a valid record exists.
`DECIDE_API_MONTHLY_CAP_EXCEEDED`	`429`	Monthly record cap is exhausted for the key or plan.	Hold the source record, request capacity, or route to a declared fallback path.
`DECIDE_API_IDEMPOTENCY_CONFLICT`	`409`	The same idempotency key was reused with a different canonical payload.	Do not execute. Reuse the key only with the original payload or create a new key for a new attempt.

Record and report API errors

Execution, outcome, CRM sync, chain, and policy report endpoints are scoped to the caller's API key. Treat their errors as missing proof until the record is successfully written or retrieved.

Code or family	Status	Endpoint family	Caller behavior
`DECIDE_EXECUTION_UNAUTHORIZED`	`401` / `403`	`/api/decision/:id/execution`	Do not mark the mutation as receipted. Fix key scope before writing execution proof.
`DECIDE_EXECUTION_IDEMPOTENCY_CONFLICT`	`409`	`/api/decision/:id/execution`	Use the original execution payload for that key or create a new key for a new attempt.
`DECIDE_OUTCOME_UNAUTHORIZED`	`401` / `403`	`/api/decision/:id/outcome`	Do not count the business result as reported. Fix key scope before submitting outcomes.
`DECIDE_OUTCOME_IDEMPOTENCY_CONFLICT`	`409`	`/api/decision/:id/outcome`	Use the original outcome payload for that key or create a new key for a revised report.
`DECIDE_CRM_SYNC_UNAUTHORIZED`	`401` / `403`	`/api/decision/:id/crm-sync`	Do not claim a CRM write-back receipt exists. Fix key scope or adapter configuration.
`DECIDE_CRM_SYNC_IDEMPOTENCY_CONFLICT`	`409`	`/api/decision/:id/crm-sync`	Keep CRM state unchanged or log a new sync attempt with a new idempotency key.
`DECIDE_CHAIN_UNAUTHORIZED`	`401` / `403`	`/api/decision/chains/:chain_id`	Do not expose chain metadata across scopes. Fix key scope before retrying.
`DECIDE_POLICY_*_UNAUTHORIZED`	`401` / `403`	Effectiveness, confidence, anomalies, benchmarks.	Do not mix reports across scopes. Fix key scope before using intelligence outputs.

Retry and fallback rules

Safe retry

Network, 502, or 5xx

Retry with backoff only when the caller can preserve the same idempotency key and no downstream mutation has happened yet.

Never approve

Auth, cap, or conflict

Unauthorized, monthly-cap, and idempotency-conflict responses are not soft approvals. Hold the action or route to review.

Operational signal

Status endpoint

GET /api/decision/status reports readiness for auth, backend wiring, idempotency, ledger, receipt signing, and registries.

Example error payload

Log error, request_id, rate headers, usage headers, and idempotency status. Do not infer a verdict when the API did not return a Decision Record.

429 rate limited

HTTP/1.1 429 Too Many Requests
Retry-After: 1
X-RateLimit-Limit: 20
X-RateLimit-Remaining: 0

{
  "c": "unclear",
  "v": "rate_limited",
  "error": "DECIDE_API_RATE_LIMITED",
  "retry_after": 1
}