> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mesh.larkwave.org/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses and errors

> One envelope on every response, and a numeric code to branch on.

Every response, success or failure, has the same four fields:

```json Success theme={null}
{
  "success": true,
  "data": { "id": "9b2e…", "account_number": "6037000014" },
  "message": "Virtual account created",
  "request_id": "01a190e05f6670a9aea1e58c02200cca"
}
```

```json Failure theme={null}
{
  "success": false,
  "data": null,
  "message": "Virtual account not found",
  "request_id": "01a190e060e6787b8e6a8ff370172731",
  "code": "61"
}
```

```json Validation theme={null}
{
  "success": false,
  "data": { "fields": { "amount_minor": ["Must be greater than 0"] } },
  "message": "One or more validation errors occurred",
  "request_id": "01a190e061f2…",
  "code": "13"
}
```

| Field | Notes |
| - | - |
| `success` | `true` or `false` |
| `data` | The result. Always present: `null` when there is none |
| `message` | Human-readable. Don't branch on it; it may be reworded |
| `request_id` | Also in the `X-Request-Id` header. Quote it to your bank's support |
| `code` | On failure only. **Branch on this.** A number is never reused |

Fields are `snake_case`, and fields with no value are left out. Validation failures list each field's problems under `data.fields`.

## Error codes

> [accordion] General (11–29)
>
> | Code | Status | Meaning |
> | - | - | - |
> | `11` | 500 | Something went wrong on our end |
> | `12` | 400 | The request is invalid |
> | `13` | 400 | Validation failed: see `data.fields` |
> | `14` | 401 | Authentication is required (bad key, address or business status) |
> | `15` | 403 | The key lacks the permission |
> | `16` | 404 | Not found |
> | `17` | 409 | Conflicts with the current state |
> | `18` | 429 | Rate limited: retry later |
> | `20` | 503 | Temporarily unavailable |
> | `21` | 502 | An upstream service is unavailable |
> | `22` | 504 | An upstream service didn't answer in time |
> | `24` | 422 | Only an active static collection account can be renamed |
> | `25` | 409 | A rename is already with the provider |
> | `26` | 404 | That bank has no account with this number |

> [accordion] Business, features and wallets (40–49)
>
> | Code | Status | Meaning |
> | - | - | - |
> | `40` | 404 | The bank has no record of your business yet |
> | `43` | 403 | This feature isn't enabled for your business |
> | `44` | 403 | The bank hasn't approved your business for virtual accounts |
> | `45` | 404 | Wallet not found |
> | `46` | 409 | The customer already has a wallet |
> | `47` | 422 | The bank hasn't recorded your settlement account yet |
> | `48` | 422 | The bank hasn't approved your business for collection |
> | `49` | 403 | The bank doesn't offer virtual accounts yet |

> [accordion] Customers (50–59)
>
> | Code | Status | Meaning |
> | - | - | - |
> | `50` | 404 | Customer not found |
> | `51` | 409 | A customer with this phone number already exists |
> | `52` | 422 | Name and date of birth can't change after identity is verified |
> | `53` | 409 | This `Idempotency-Key` was used with a different request |
> | `54` | 400 | An `Idempotency-Key` header is required |
> | `55` | 422 | A customer's details can't change through the API once they reach tier 1 |
> | `56` | 422 | The customer is deactivated |

> [accordion] Accounts (60–69)
>
> | Code | Status | Meaning |
> | - | - | - |
> | `60` | 404 | No account with this number belongs to your business |
> | `61` | 404 | Virtual account not found |
> | `62` | 409 | The customer is still being set up with the bank: retry in a few seconds |
> | `64` | 409 | You already have a dynamic account with this reference |
> | `65` | 409 | Only a dynamic account still waiting for its payment can be cancelled |
> | `66` | 422 | The customer isn't eligible for a wallet: verify them to a higher tier |
> | `67` | 422 | You hold as many virtual accounts as the bank allows |
> | `68` | 422 | Over the customer's KYC tier limit |
> | `69` | 404 | No transaction with this id on this account |

> [accordion] Verifications (70–79)
>
> | Code | Status | Meaning |
> | - | - | - |
> | `70` | 404 | Verification not found |

> [accordion] Transfers, settlements and payments (80–89)
>
> | Code | Status | Meaning |
> | - | - | - |
> | `80` | 422 | Not enough for this amount and its charges |
> | `81` | 422 | A closed-loop business's customers' money can go only to its wallets or its other customers |
> | `82` | 403 | Only a closed-loop business can take money from its customers' wallets |
> | `83` | 422 | Over the account's single-transfer or daily limit |
> | `84` | 404 | Transfer not found |
> | `85` | 422 | The account is restricted or not active |
> | `86` | 422 | Payouts and settlements leave only from your own wallet, or the bank turned this off |
> | `87` | 422 | Not enough in the wallet to settle |
> | `88` | 404 | Payment not found |
> | `89` | 409 | The payment isn't held for a decision |

> [accordion] Webhooks (90–99)
>
> | Code | Status | Meaning |
> | - | - | - |
> | `90` | 404 | No webhook URL is set for this mode |
> | `91` | 404 | Webhook delivery not found |
> | `92` | 404 | Event not found |
> | `94` | 409 | The previous secret is still valid; rotate again after its overlap ends |
> | `95` | 422 | The webhook URL is disabled: enable it to test or replay |
> | `96` | 409 | The delivery is being sent right now: retry the replay in a moment |

## Retrying

* **Safe to retry:** `429`, `502`, `503` and `504`. Wait a moment, and send a create again with the **same** `Idempotency-Key`.
* **Don't retry unchanged:** `400`, `401`, `403`, `404`, `409` and `422`. Fix the request first.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.