Errors and response format for the Bitliva Merchant API - BITLIVA Merchant API

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

{
  "status": "success",
  "message": "Customer retrieved successfully.",
  "data": {}
}

{
  "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.