Errors & response format
Every Whish Money API speaks the same envelope. Learn it once and error handling is the same everywhere.
- HTTP is always 200
- Branch on
statusthencode 500means pending, not failed- Match code strings exactly
The response envelope
Every endpoint returns HTTP 200 with Content-Type: application/json and the same envelope. Branch on the status and code fields in the body, never on the HTTP status code.
| Field | Type | Description |
|---|---|---|
status | Boolean | true when the call was accepted and processed. false when it was not. |
code | String | null whenever status is true. An operation-specific error code when status is false; the value 500 is special (see below). This field only ever reports errors, never a transaction's progress. |
dialog | Object | Optional title / message for display to the end user. |
data | Object | Operation payload on success; shape varies per endpoint (and may be a scalar or null). |
actions / extra | Object | Reserved; typically null. |
retrieved | Boolean | Present on idempotent operations. true means the response replays an already-processed request (it was not run again). |
How to interpret the outcome
The two fields move together, so read them as a pair. There are only these combinations:
status | code | Treat as |
|---|---|---|
true | null | Succeeded. Process data. |
false | 500 | Pending. Outcome unknown; escalate to Whish and do not mark it failed. |
false | any other code | Failed, unless that code is a documented challenge for the endpoint you called. |
A status: true is never accompanied by a code, and a code never reports how far a transaction has progressed. Where an operation has a lifecycle of its own, the endpoint reports it on a separate field inside data (for example Whish Pay's collectStatus), which is unrelated to the envelope status.
Some endpoints return status: false for an expected challenge rather than a failure. The clearest example is Bills: a bill.requires_provider_otp code means the biller needs a one-time password, so you continue the flow rather than treating it as an error. Always check the endpoint reference for the codes it can return.
Working with error codes
- Match codes exactly. Error codes are the literal values returned by the API and are reproduced verbatim in the docs, including any unusual spelling. Compare against the exact string.
- Show
dialog.messageto users, branch oncode. Usecodefor programmatic logic and surfacedialog.messagein your UI. - Only
code: 500escalates. Treat it as pending and follow up with Whish. Every other non-success code is a final result you can resolve automatically. - Per-API catalogs. Each API reference lists the exact codes its endpoints return, with a short description and the action to take.
The pending case (code: 500)
A code: 500 means an internal error left the outcome unknown, not that the operation failed. It is common for Mobile Wallet money transfers and rare elsewhere. Map it to Pending, keep your record open, and recover the real result by reconciling:
- Whish APIs (Whish Pay, Bills, Vouchers, Variable Topup, and the others on
api.whish.money): resend the same request with the sameexternalId. An already-processed request returns its original result withretrieved: true, so you never double-charge. - International Money Transfer (
api.woocash.money): resend the same request with the sameRequest-id. A repeat is not duplicated and answerstransfer.already.done; read the outcome with Get transfer status using thatrequestId. See the Reliability guide.