Errors and retries

An unsuccessful response and an unsuccessful economic operation are different facts. Reconcile before creating a new instruction.

The error envelope below illustrates the proposed order contract. Order-specific codes and their HTTP mapping remain proposals and must be checked against the released environment contract.

http

HTTP/1.1 409 Conflict
Content-Type: application/json

{"version":"0.1-review","requestId":"request_demo_5","code":"IDEMPOTENCY_CONFLICT","message":"Request differs from the original instruction","retryable":false}

HTTP / proposed code	Client behavior
400 `INVALID_REQUEST`	Correct malformed amounts, unsupported fields, tick/step violations or order shape. Do not round a monetary request silently.
401 `UNAUTHENTICATED`, 403 `FORBIDDEN`	Restore current access to the same account before lookup or retry. Account selection does not authenticate.
404 `NOT_FOUND`	Recheck the account and resource ID; do not assume a private resource exists elsewhere.
409 `IDEMPOTENCY_CONFLICT`, `INVALID_STATE`, `QUOTE_EXPIRED`	Reconcile the original operation/current order. Expired quote terms need new acceptance.
422 `INSUFFICIENT_FUNDS`, `INSUFFICIENT_LIQUIDITY`	Refresh funds and executable liquidity. A partial fill follows the admitted order policy; it must not be inferred from this error.
429 `RATE_LIMITED`, 503 `TEMPORARILY_UNAVAILABLE`	Preserve the request/key; follow applicable retry guidance and reconcile before another submission. Rate limits and retry timing remain unspecified.

After a timeout, persist the account, original method/path/body and key. Recover using the operation ID or exact idempotent request; never generate a fresh order merely because an acknowledgement was lost. The target order API must supply an authoritative order-operation lookup before this recovery pattern can be used for orders.