Response envelope
Success responses always wrap the payload:Parse rule of thumb: check
success; on false, switch on code — never on
message text, which can be reworded at any time. Some errors carry
additional structured context alongside these fields (for example, payout
rejections include a consistency block).Common codes
Endpoint-specific codes (for example payout
OPEN_EXPOSURE,
CONSISTENCY_BLOCKED) are documented on each endpoint in the
API Reference.
Retry guidance
ENGINE_UNREACHABLEand any 5xx: retry with the same idempotency key — 5xx responses are never cached, so the retry re-executes safely.REQUEST_TIMEOUT(504): a completed error response meaning the GET took too long. Narrow the request (shorter date range, fewer filters) or retry. Unlike write operations, this error is never mid-write — the request simply did not complete in time.IDEMPOTENCY_KEY_IN_PROGRESS(409): your own duplicate is still running; back off briefly and retry to receive the cached response. Ifstaleis true, the request may have stopped before finishing — follow Recovering a stuck key.IDEMPOTENCY_KEY_REUSED(409): this key was already used for a different request body. Don’t retry with it; send the new request with a fresh key.- 4xx validation errors: fix the payload and use a fresh idempotency key.