Keep the source and stage of an error: HTTP transport, webapp validation/readiness, native simulation, CheckTx admission or committed DeliverTx. A single invented numeric error list cannot represent all of them. The same transport failure calls for a read retry or signed-identity reconciliation depending on the operation.
An LCD/gRPC-gateway error may have code, message and details. That code is
not automatically a Structs ABCI code. CometBFT admission/block results carry
codespace, code and log/result fields. Preserve those fields together and the
transaction hash, request stage and committed coordinates when available.
Do not assume HTTP 200 means a transaction succeeded, or that an entity lookup always uses one HTTP status. Validate the endpoint’s result shape and identity.
The application DTO uses success, errors, data, and where applicable meta.
Success commonly has errors: []; failure can contain keyed error messages. Server,
proxy or framework errors may return another body entirely. Reject a non-success
HTTP response before trusting parseable JSON as current data.
{
"success": false,
"errors": {"signature_validation_failed": "Invalid signature"},
"data": null
}
Incomplete financial/catalog/work evidence may carry readiness/reason metadata and HTTP 503. Unknown raw values remain null. An unavailable read is not an empty valid result or permission to use zero. See read-model protocol.
| Status | Typical handling |
|---|---|
| 400 | Validate the request; diagnose native result fields separately |
| 401 | Reauthenticate a private read once; a failed login must not recurse |
| 403 | Check actual route/authority; do not broaden keys automatically |
| 404 | Verify resource/context and whether the result is authoritative |
| 409 | Resolve the reported state/identity conflict; retain the original request |
| 429 | Apply bounded backoff for repeatable reads |
| 5xx | Treat as unavailable; repeat reads within budget, observe attempted sends |
A proxy status is not definitive evidence that a native broadcast never reached a node.
Use native code reference and
error data structures. structs and structs-ante are
different codespaces; Cosmos modules and transport layers also define their own.
A zero CheckTx code proves admission, while a zero committed DeliverTx code proves
execution success for that exact transaction.
Read timeouts/rate limits/transient failures may be retried within bounds. Invalid proofs, payloads or permissions require diagnosis. Temporary game conditions may permit a later revalidated action; they do not authorize blind retransmission. A signed unknown outcome must retain its bytes/hash and reserve its signing context.
Use deadlines, jitter, an attempt budget and route/session cancellation for reads. Coalesce identical requests and cancel stale consumers. Do not wrap signing or broadcast in a generic HTTP retry helper.
A readiness probe may wait for the next observation interval. It must still reject wrong-chain, old-session or older snapshots. A cached timestamp is not native authority.
Respect a valid Retry-After within the overall read budget. For attempted sends, reconcile the saved identity unless a definitive native rejection is established. See retry strategies.
Verify the ID and current source. Distinguish a complete empty result from unavailable or truncated evidence. A missing transaction-search result alone proves neither non-inclusion nor permission to create another payment.
Read exact spendable vault funds and current action requirements. Total inventory, retained funds and unbonding receipts are not automatically spendable. A later action may be prepared after funding/charge changes and the prior outcome is established.
Refresh authoritative capacity/load and target state. Do not infer online status from a failed request or a fallback zero. Shared player/charge limits remain shared across keys and paid transactions.
Reconnect, reauthenticate if appropriate, restore subscriptions and refresh state. Retain signed evidence and observe its original identity. GRASS reconnect supplies invalidation opportunities, not durable event replay or transaction cancellation.
success, identity and applicable readiness metadata.The API code reference lists selected release-native codes and links their source. There is no universal “1–9” game-error mapping.
An API timeout while reading funds permits a bounded read retry. A timeout after sending signed transfer bytes requires observing that hash. A committed failure returns the transfer to its existing confirmation with the same recipient/amount; a later confirmed action can be prepared from fresh state.
Action protocol defines one-send identity and outcomes. Authentication defines session/token recovery. State and data defines coherent cache updates.
Exercise actual transport boundaries: HTTP failure with valid JSON, lost send acknowledgement, admission without inclusion, committed failure, reload while unknown, notification loss, wrong-session late replies and incomplete native data. Assert the original hash/bytes and send count survive; checking only an error string cannot establish duplicate prevention.
Verified against: webapp 43bc1086, TSA 3258529, official structsd 96cea3a.