Errors, limits & failure behavior

HTTP and reason codes

Only the 401 boundary is live for /v1 today. Other rows define the proposed platform behavior. Correlate the error with a server-issued request ID.

HTTP	Reason	Client action
401	unauthorized	Access is closed or credentials are invalid; no retry loop
403	policy_denied / scope_denied	Review the authorized policy and scopes
409	revision_conflict / idempotency_conflict	Refresh the revision; do not reuse a key with another payload
422	grammar_invalid / action_graph_invalid	Fix structure or unsupported configuration
429	rate_limited / budget_cap	Respect Retry-After or review the budget
502	upstream_failure	Inspect the recorded outcome before retrying
503	required_control_unavailable	Keep the protected route blocked
504	deadline_exceeded	Cancel child work; processing may already have occurred

Error envelope

Messages should not echo prompts, credentials, private output or full policy internals. Details can identify a schema path and stable public reason.

json

{
  "error": {
    "code": "grammar_invalid",
    "message": "Response did not satisfy the required grammar.",
    "request_id": "req_example"
  }
}

Retries and partial results

After an interrupted inference request, absence of a response does not prove absence of processing or cost. Account and reconcile attempts. Retry only under the operation contract and budget. Never retry a committed side effect without its durable idempotency record.

No silent weakening

Required-check timeouts, stale policy, unsupported features and unknown eligibility facts do not turn into an unprotected request. Any optional branch behavior must be configured, visible and unable to claim protection after release.