API Errors vs Empty Blockchain Query Results
Distinguish a successful query with no matching records from unavailable data, authentication failures and partial responses in blockchain integrations.
Overview
When translating these concepts into an integration, keep the scope described by the wallet history api with the result. The examples in wallet transaction history and smart contract event logs show how the same distinction affects neighbouring data questions.
An empty array is meaningful only after the request and coverage conditions are understood. Turning every exception into an empty result makes service failures look like wallets with no activity.
Keep transport and domain states
Separate HTTP or transport failure, valid empty result, partial coverage and unsupported query. A 200 response can still contain method-level errors under some protocols. Parse the documented response envelope before interpreting data. Keep safe diagnostic codes available without leaking credentials or sensitive request details.
Worked example: a hidden outage
A wallet-history call times out. A catch handler returns an empty array and the UI announces no transactions. The user sees a factual claim that was never established. Return an unavailable state instead, while retaining the last known result with a clear freshness label if the product policy permits it.
Test every branch
Include wrong credentials, wrong network, unsupported date range, malformed JSON and a genuine zero-match response. A partial page should not be marked complete. Downstream exports and calculations must preserve uncertainty rather than converting it to zero balances or zero valuations. Retry only eligible operations under a bounded policy.
A practical acceptance test
Return a valid zero-match response, an authentication failure, malformed JSON and a partial page. Assert four distinct outcomes all the way into the UI and export. A generic catch handler must not turn the last three into no activity. Retrying an eligible read should preserve the original range and stop under a bounded budget.
Questions about the topic
Frequently asked questions
Does an empty array always mean no history?
No. First establish that the query succeeded with the intended coverage.
Should every exception become an empty result?
No. That disguises failure as a factual answer.
Standards & technical documentation