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

# Errors and response format for the Bitliva Merchant API

> Every Bitliva response uses one envelope. Learn the error codes, HTTP statuses, validation errors, and how to retry safely with references.

Every Bitliva Merchant API response uses the same envelope, and every error carries a stable `code`. Match on `code` in your integration and never on `message`, because message text can change.

## Response envelope

```json Success theme={null}
{
  "status": "success",
  "message": "Customer retrieved successfully.",
  "data": {}
}
```

```json Error theme={null}
{
  "status": "error",
  "message": "Invalid or missing API key.",
  "code": "invalid_api_key"
}
```

| Field | Type | Description |
| - | - | - |
| `status` | string | `success` or `error`. |
| `message` | string | A human-readable summary. Do not parse it. |
| `data` | object | Present when there is something to return. |
| `code` | string | On errors only. A stable machine-readable error code. |
| `errors` | object | On `validation_failed` only. Field errors keyed by field name. |

## Error codes

| HTTP status | `code` | Meaning |
| - | - | - |
| 401 | `invalid_api_key` | The API key is missing, wrong or revoked. |
| 403 | `account_inactive` | Your merchant account is not active. Contact support. |
| 403 | `live_not_enabled` | Live access is not enabled: your business is not verified yet, or the account is suspended. |
| 403 | `sandbox_only` | This endpoint only exists in the sandbox. |
| 404 | `not_found` | Nothing with that id. |
| 404 | `customer_not_found` | No customer with that id found. |
| 405 | `method_not_allowed` | That endpoint does not accept this HTTP method. |
| 409 | `reference_conflict` | This reference was already used for a different request. Use a new reference. |
| 409 | `customer_pending` | This customer is still being set up. Retry in a moment with the same reference. |
| 422 | `validation_failed` | One or more fields are missing or invalid. `errors` lists them by field name. |
| 422 | `unsupported_currency` | That coin is not supported. |
| 422 | `invalid_network` | The network is missing or not valid for that coin. |
| 422 | `amount_below_minimum` | The amount is zero, or below the minimum for this action. The message states the minimum. |
| 422 | `insufficient_crypto_balance` | The customer does not hold enough of that coin for this sale. |
| 422 | `insufficient_wallet_balance` | Your naira wallet does not hold enough for this purchase. Top up in the dashboard. |
| 422 | `sale_not_possible` | The sale could not be started, most often because the customer's balance is too low or the amount is too small to price. Check the balance and retry. |
| 422 | `address_required` | The customer needs a deposit address for that coin first. Generate one, then retry. |
| 422 | `customer_limit_reached` | The sandbox customer limit has been reached. |
| 422 | `giftcard_unavailable` | That gift card cannot be sold right now, or does not exist. |
| 422 | `giftcard_submission_failed` | The gift card could not be submitted. |
| 429 | `rate_limited` | Too many requests. Wait the number of seconds in the `Retry-After` header. |
| 502 | `service_unavailable` | Something went wrong on our side. |
| 503 | `temporarily_unavailable` | This action is temporarily unavailable. |

## Retry safely with references

Creating a customer, buying or selling crypto, and selling a gift card all take a `reference` that you choose. Reusing a reference makes these calls safe to retry:

* Sending the same reference again returns the original result instead of doing the action twice.
* Sending a reference that was already used for a different request returns `reference_conflict`. Use a new reference for a new action.
* If you get `customer_pending`, wait a moment and retry with the same reference.

After a `429`, wait for the `Retry-After` period. After a `502` or `503`, retry the same request with the same reference.


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