# Errors

> HTTP status codes and stable error codes of the Fina Pay and storefront APIs.

Fina Pay answers errors as `{ "error": "<code>" }`. Storefront APIs use the envelope `{ "data": null, "error": { "code", "message", "details"? }, "request_id" }`. In both cases branch on the code.

| HTTP | Fina Pay code | What to do |
| --- | --- | --- |
| 400 | `invalid_json`, `invalid_amount`, `missing_params` | Fix the request. `amount_minor` must be an integer > 0. |
| 401 | `unauthorized` | Check the secret key and that the connection is active. |
| 400 | `reference_required`, `invalid_reference`, `same_account`, … | Payout request errors, see [Payouts](https://fina.do/developers/payouts.md). |
| 403 | `payouts_disabled` | Turn on Payouts via API for the connection. |
| 404 | `not_found` | The charge or payout does not exist or belongs to another connection. |
| 404 | `recipient_not_found` | No active Fina Pay wallet with that account number or phone. |
| 409 | `insufficient_funds`, `currency_mismatch`, `wallet_blocked` | The payout was not sent; nothing moved. |
| 409 | `not_cancellable` | The charge is no longer `pending`. |
| 429 | `rate_limited` | Back off and retry (60 requests/minute per connection). |
| 5xx | — | Retry with exponential backoff; reuse the same `reference`. |

Each storefront spec lists its codes per status in its OpenAPI (`responses`). Common ones: `UNAUTHENTICATED`, `APP_NOT_FOUND`, `BUSINESS_INACTIVE`, `OUT_OF_DELIVERY_ZONE`, `SHIPMENT_LIMIT_EXCEEDED`, `INSUFFICIENT_STOCK`, `RATE_LIMITED`.

Source: https://fina.do/developers#errors