Skip to main content

​
Problem details

Non-2xx responses use application/problem+json:
Common stable codes include idempotency_conflict, quota_exceeded, and join_timeout, plus problem codes mapped from schema, authentication, concurrency, and resource-state failures. Treat new codes as an unknown error rather than failing to parse them.

​
Run business errors

Successful creation returns 202 pending. A later node/schema/provider error moves the resource to failed, timed_out, or dead_letter and populates:
The get/join HTTP request itself may still return 200. Clients must inspect both HTTP status and run.status.

​
SSE format and resume

  • Events are persisted in PostgreSQL before delivery.
  • sequence increases from 1 within a run.
  • Reconnect with the last processed Last-Event-ID; the server starts at the next event.
  • Deduplicate on (run_id, sequence) to handle repeated delivery.
  • Lines beginning : heartbeat are keep-alive comments and should be ignored.
  • The server closes the stream when the run becomes terminal or paused.

​
Retry policy

  1. Use bounded exponential backoff only for retryable=true, network failure, 429, and transient 5xx.
  2. Honor Retry-After.
  3. Reuse the same Idempotency-Key and identical body when retrying run creation.
  4. Resume SSE from the last sequence; do not create a new run.
  5. Do not automatically redrive deterministic schema or tool-permission errors.
The same request key with a different body returns 409 idempotency_conflict. Do not silently switch to a random key after conflict; that hides a caller bug and may duplicate business work.