Skip to main content

Retry strategy

  • Honour Retry-After on every 429 and 503.
  • Use exponential backoff (for example 2 s, 4 s, 8 s, capped at 60 s) for 500 and for 503 without Retry-After.
  • Never retry other 4xx responses: fix the request instead.
  • For a 202, poll the job (cost 1), not the wallet (cost 5).

200-level outcomes that are not errors

  • Partial coverage: coverage.status: "partial"; one or more protocols have status error or skipped with an error_code (an open enum, for example ADAPTER_QUARANTINED, BUDGET_EXCEEDED, DEADLINE_EXCEEDED).
  • Null values: value_usd: null on a leg and total_value_usd: null with total_null_reasons. Unknown is not zero.
  • Skipped protocols: an adapter can be skipped (not approved, quarantined, disabled, over budget); positions in it are not ruled out.

Handling null and partial values

  • totals.total_value_usd: null comes with totals.total_null_reasons (for example indicative_legs when a leg is priced from a thin market). Show known_value_usd instead, labelled as partial.
  • known_value_usd adds priced and indicative legs. It is not a lower bound when a debt is unpriced.
  • A leg with value_usd: null has a valuation_status that says why (unsupported, no_liquidity, stale, …).
  • Never treat null as zero. Unknown values are null; a real zero is "0". Amounts and USD values are decimal strings: parse them with a decimal library, not floating point.