> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.shimi.cash/responses-and-idempotency/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.shimi.cash/_mcp/server.

# Responses & idempotency

## Response formats

Response shapes differ by section. Each endpoint in the API reference shows its exact responses.

| Shape                                                     | Used by                                                             |
| --------------------------------------------------------- | ------------------------------------------------------------------- |
| `{ "status": "success" \| "error", "message"?, "data"? }` | Customers, transactions, virtual accounts, corporate, crypto, cards |
| `{ "success": true \| false, "message"?, "data"? }`       | VTU (airtime, data, bills) and List Customers                       |
| `{ "message", "data" }` or `{ "error": "..." }`           | Payouts                                                             |
| Bare array                                                | List Settlement Accounts and List Supported Banks                   |

Validation errors return `400` with `{ "status": "error", "message": "Validation error", "details": [ ... ] }`. Corporate endpoints use their own `errors[]` format.

## Idempotency and outcomes

| Section      | Idempotency key                                                | Uncertain outcome                                                                                |
| ------------ | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| Payouts      | Header named exactly `idempotencyKey` (a new value per payout) | `202`: still processing. Get the final result from the payout webhook or **Check Payout Status** |
| VTU          | `idempotencyKey` in the JSON body                              | `200` with `status: "PENDING"`. **Do not retry**; check **Fetch Single VTU Transaction**         |
| Card funding | None                                                           | `400 "Card funding is being confirmed. Do not retry..."`                                         |

> **Warning**
>
> For payouts, the header must be named `idempotencyKey`. `Idempotency-Key` is not recognised and returns `400 Idempotency key is required`.

### Retrying safely

Use a **new key for every new transaction**. To retry the *same* transaction after a network error on your side, resend the identical key:

* **VTU** returns the existing transaction.
* **Payouts** return `400 Transaction already processed`. Check the payout status instead.

## Refunds

Definite rejections from a provider are **refunded automatically** before you get the response.

Timeouts are **never refunded automatically**, because the provider may have delivered. Shimi reconciles them.

> Response formats, safe retries and how to handle uncertain outcomes when moving money.