# Errors > Status codes, error codes, field errors, rate limits, request IDs, and how to retry safely. Source: https://abuna.app/docs/errors This page lists every error the API returns, so you can handle each one in your code. A failed request returns a `4xx` or `5xx` status and a JSON body. The body has a `code` that stays the same and an `error` sentence for developers. Branch on the status and the `code`. Don't parse `error`, since its wording can change. **Error body** ```json { "code": "unauthenticated", "error": "missing or invalid API key" } ``` ## Request IDs Every response, failed or not, has an `X-Request-Id` header, like `req_01J9ZQB21C3D4E5F6G7H8J9K0M`. Log it with your own record of the request. When you contact support about a request, quote its `X-Request-Id`. ## Field errors When a request fails because of its input, the body also has an `errors` array, with one item per field. A failed validation returns `422` with code `invalid` and lists every field that failed. **Field errors (422)** ```json { "code": "invalid", "error": "email is required; phone_number is required", "errors": [ { "field": "email", "code": "required", "error": "email is required" }, { "field": "phone_number", "code": "required", "error": "phone_number is required" } ] } ``` Each item's `code` is one of these: - `required`: the field is missing or blank. - `invalid`: the value isn't allowed, such as an amount of `0` or an unknown status. - `currency_unsupported`: the currency isn't `XAF`, `XOF` or `USD`. - `phone_invalid`: the phone number has no country code, or the wrong number of digits for its country. - `phone_country_unsupported`: your payment provider can't charge phone numbers from that country. Checkout and the customer portal refuse them. - `phone_required`: the customer has no phone number yet, so there is no number to charge. See [`phone_required`](https://abuna.app/docs/errors.md#error-codes) below. - `unchanged`: the value is the one already set, such as a new price amount equal to the current one. - `too_soon`: the date is too close, such as a price change less than 14 days ahead. - `too_long`: a payment `note` is over 500 characters. - `unknown_field`: an update sent a field the endpoint doesn't take. - `invalid_json`: the value has the wrong type, or the endpoint doesn't take the field. The response is a `400`. - `price_not_eligible`: the subscription can't move to the `price_id` you sent. - `not_found`: the ID in the field doesn't exist in the app, such as a `price_id` or an `invoice_id` when you create a session. - `url_invalid`: the URL isn't an absolute URL with a host, or uses `http` where only `https` is allowed. A product's slug must be unique in its app. A slug you send that another product has returns `409` with code `slug_taken`, and its `errors` item names the `slug` field. A slug Abuna makes from the name never clashes. ## Error codes These are the codes a request with a secret key can get. Each code shows the HTTP status it comes with. **Error codes** - `invalid_json` (400): The body is empty, isn't valid JSON, has a value of the wrong type, or has a field the endpoint doesn't take. For a wrong type or an unknown field, errors names the field. - `live_app_required` (400): You asked to [copy products from Test to Live](https://abuna.app/docs/api/products.md#copy-from-test) with a Test app ID. Use the Live app ID. - `test_app_required` (400): You asked to [copy products from Live to Test](https://abuna.app/docs/api/products.md#copy-from-live) with a Live app ID. Use the Test app ID. - `invalid` (422): One or more fields failed validation. See `errors` for each field. An `Idempotency-Key` header longer than 255 characters gets this code with `400`. - `payment_declined` (402): The payment failed. The provider can also give a more specific reason, listed below. - `insufficient_funds` (402): The customer's balance is too low. - `payment_not_approved` (402): The customer declined the prompt on their phone or let it time out. - `wallet_not_found` (402): The number has no wallet on the network charged, or isn't a valid number. - `wallet_limit_reached` (402): The customer's wallet reached a transaction or balance limit. - `wallet_busy` (402): Another payment is already waiting for the customer's approval. - `network_unavailable` (402): The network can't take this payment now, or can't take it at all on your provider account. - `amount_too_low` (402): The amount is below the smallest payment your provider takes, so trying again won't help. - `unauthenticated` (401): The request has no key, or the key is wrong or revoked. Check the Authorization header. - `forbidden` (403): A secret key called an endpoint that needs a dashboard sign-in, or a dashboard sign-in or publishable key called one that needs a secret key, like sessions. - `email_unverified` (403): The app is in Live mode and the team owner hasn't verified their email. - `plan_limit` (403): The request would pass a limit on your plan, such as its number of Live subscribers. - `plan_read_only` (403): Your plan has made this Live app read-only. Reads still work, and so does charging an invoice. - `not_found` (404): The object named in the path doesn't exist in the app, or, when you create a price or a subscription, an ID you sent doesn't; errors then names that field. An app ID that doesn't exist, or that your key doesn't belong to, gets this too. - `slug_taken` (409): Another product in the app already has the slug you sent. Send a different slug. - `code_taken` (409): Another [promotion code](https://abuna.app/docs/api/promotion-codes.md) in the app already has this code. Codes ignore case, so `BLACKFRIDAY` and `blackfriday` are the same. Send a different code. - `test_app_missing` (409): The app has no Test mode to copy products from. - `already_paid` (409): The invoice is already paid. - `invoice_not_open` (409): The invoice is void, for example because the subscription was canceled. You can't create a session to pay it. - `subscription_canceled` (409): The subscription has ended, so a scheduled cancel can't be undone and you can't request a cancel. Create a new subscription instead. - `subscription_not_active` (409): You can request a cancel only for an active or unpaid (past_due) subscription. A pending one, whose first period isn't paid yet, gets this. - `cancel_already_scheduled` (409): The subscription is already scheduled to cancel, so you can't request a cancel. - `payment_in_progress` (409): A payment for this invoice is already waiting for approval. A plan change or cancel that would void an unpaid period, or replace an upgrade waiting for payment, also gets this while that payment is in flight. - `plan_change_unavailable` (409): The subscription isn't active or unpaid (past_due), so its plan can't change. A subscription whose first period isn't paid yet can't change plan. - `renewal_paid_early` (409): The customer already paid the next period before it started, so an upgrade waits until that period starts. Nothing was charged. - `session_not_open` (409): The session is already completed or expired, so it can't be expired. - `idempotency_in_progress` (409): A request with the same Idempotency-Key is still running. Retry after a moment. - `no_pending_change` (409): The price has no scheduled change to cancel. - `change_in_effect` (409): The price's pending change has reached its effective_at and is taking effect, so it can't be replaced or canceled. This lasts from effective_at until the price_change.applied event, usually under a minute. Then you can schedule a new change. - `conflict` (409): The request conflicts with the current state of the object. - `price_archived` (410): The price, or the product it belongs to, is archived, so no new subscription can use it. - `already_subscribed` (409): At checkout, the customer already has an active or unpaid (past_due) subscription to this price, matched by email. The phone number doesn't count, so the same phone with another email goes through. Nothing was created or charged. The checkout page offers to email them their subscription links. A subscription still waiting for its first payment doesn't cause this: the checkout takes the customer back to that payment. Neither does a subscription to another price, or one that was canceled or has ended. - `session_expired` (410): The session expired before the customer submitted their details. The hosted checkout page gets this, not your server. Create a new session. - `price_not_eligible` (422): The subscription can't move to this price: it is the current price, archived, for another product, in another currency, or not in the app. The error sentence of its price_id item says which one; read it, but don't branch on it. - `coupon_invalid` (422): A discount you sent in `discounts` can't be used on this checkout or subscription: the coupon or code is unknown, inactive, expired, used up, for other products, in another currency, or would take the amount below the minimum charge. The `errors` item names `discounts`. - `promotion_code_invalid` (422): The customer's code is unknown, inactive, expired, used up, or its coupon is no longer valid. The `errors` item names `code`. Customers see it beside the field as “This code doesn't work. Check how it's spelled, or ask the seller for a current code.” - `promotion_code_not_applicable` (422): The code's coupon is for other products, or in another currency. The `errors` item names `code`. - `promotion_code_amount_too_low` (422): The code's coupon would take the amount below the minimum charge: 100 XAF or XOF, or 50 USD cents. The `errors` item names `code`. - `promotion_code_first_time_only` (422): The code is for customers who never paid this app, and this customer has. The `errors` item names `code`. - `not_accepting_payments` (422): The Live app can't take payments yet: the team owner hasn't verified their email, no payment provider is connected, or the app has no support email or URL. The `payments` object on [the app](https://abuna.app/docs/api/apps.md#object) says what is missing. An upgrade with something to pay gets this too. - `payment_unavailable` (422): The payment method isn't offered. - `phone_required` (422): You asked to [charge an invoice](https://abuna.app/docs/api/invoices-and-payments.md#charge), but the customer has no phone number yet. A customer who came through checkout has none until they first pay. The `errors` item names `phone_number`. Set a number with [Update a customer](https://abuna.app/docs/api/customers.md#update), or send them a [payment session](https://abuna.app/docs/api/sessions.md#create-payment), which asks for it. The pay page gets this too when it sends no number for such a customer. - `idempotency_key_reused` (422): The Idempotency-Key was already used with a different request in the last 24 hours. Use a new key for a new request. - `webhook_url_missing` (422): You asked to send or resend a webhook, but the app has no webhook URL. - `rate_limited` (429): Too many requests. See [Rate limits](https://abuna.app/docs/errors.md#rate-limits). - `internal` (500): Something went wrong on Abuna's side. Retry later. - `payment_paused` (503): You asked to [charge an invoice](https://abuna.app/docs/api/invoices-and-payments.md#charge), but no new payment was started. An earlier payment on the invoice may still be in progress. Try again in about a minute. - `exchange_rate_unavailable` (503): The invoice is in USD and no recent exchange rate is available, so it can't be paid right now. Nothing was charged. Try again later. Rates are normally available every day. Customers on the pay page are asked to try again later. See [Paying in FCFA](https://abuna.app/docs/amounts-currencies-and-timestamps.md#paying-in-fcfa). ## Rate limits - Each IP address can make 600 requests a minute. - Each app can send 10 test webhooks a minute. Past a limit, the API returns `429` with code `rate_limited`, and a `Retry-After` header. Wait that many seconds, then try again. **Rate limited (429)** ```json { "code": "rate_limited", "error": "too many requests" } ``` ## Idempotent requests Every `POST` and `DELETE` accepts an `Idempotency-Key` header, so you can retry a request after a network error or a `5xx` without doing the work twice. Send a new random value, up to 255 characters, for each new request, and the same value on each retry of it. Without the header, every request runs. **POST /v1/apps/{appID}/sessions with Idempotency-Key** cURL: ```bash curl https://api.abuna.app/v1/apps/8ddhXCDW/sessions \ -H "Authorization: Bearer sk_test_..." \ -H "Content-Type: application/json" \ -H "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43" \ -d '{ "type": "checkout", "price_id": "Zt6YbN3q", "metadata": {"user_id": "42"} }' ``` Node.js: ```javascript const response = await fetch("https://api.abuna.app/v1/apps/8ddhXCDW/sessions", { method: "POST", headers: { Authorization: "Bearer sk_test_...", "Content-Type": "application/json", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43", }, body: JSON.stringify({ type: "checkout", price_id: "Zt6YbN3q", metadata: { user_id: "42" }, }), }); const session = await response.json(); ``` Python: ```python import requests response = requests.post( "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", headers={"Authorization": "Bearer sk_test_...", "Idempotency-Key": "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"}, json={ "type": "checkout", "price_id": "Zt6YbN3q", "metadata": {"user_id": "42"}, }, ) session = response.json() ``` PHP: ```php true, CURLOPT_HTTPHEADER => ["Authorization: Bearer sk_test_...", "Content-Type: application/json", "Idempotency-Key: 6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43"], CURLOPT_POSTFIELDS => json_encode([ "type" => "checkout", "price_id" => "Zt6YbN3q", "metadata" => ["user_id" => "42"], ]), CURLOPT_RETURNTRANSFER => true, ]); $session = json_decode(curl_exec($ch), true); ``` Go: ```go body, _ := json.Marshal(map[string]any{ "type": "checkout", "price_id": "Zt6YbN3q", "metadata": map[string]any{"user_id": "42"}, }) req, _ := http.NewRequest("POST", "https://api.abuna.app/v1/apps/8ddhXCDW/sessions", bytes.NewReader(body)) req.Header.Set("Authorization", "Bearer sk_test_...") req.Header.Set("Content-Type", "application/json") req.Header.Set("Idempotency-Key", "6f1c2b9e-4d3a-4c8e-9a7f-2e5b8d1c0a43") res, err := http.DefaultClient.Do(req) if err != nil { log.Fatal(err) } defer res.Body.Close() var session map[string]any json.NewDecoder(res.Body).Decode(&session) ``` Abuna keeps a key for 24 hours, per app. When a request reuses a key: - The same request, to the same path with the same body, gets the first response again, with its status and body, plus the header `Idempotent-Replayed: true`. - A different request returns `422` with code `idempotency_key_reused`. - While the first request is still running, it returns `409` with code `idempotency_in_progress`. A request that charges a customer can run for up to a minute, so keep retrying every few seconds for that long. - If the first request got a `5xx`, the key isn't kept, so the retry runs again. - Any other response is kept, errors included. A `4xx`, like a declined payment, comes back the same for 24 hours. To try again after one, send a new key. A key longer than 255 characters returns `400` with code `invalid`.