Getting started
Errors
Status codes, error codes, field errors, rate limits, request IDs, and how to retry safely.
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.
{
"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.
{
"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 of0or an unknown status.currency_unsupported: the currency isn'tXAF,XOForUSD.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. Seephone_requiredbelow.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 paymentnoteis 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 a400.price_not_eligible: the subscription can't move to theprice_idyou sent.not_found: the ID in the field doesn't exist in the app, such as aprice_idor aninvoice_idwhen you create a session.url_invalid: the URL isn't an absolute URL with a host, or useshttpwhere onlyhttpsis 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_json400The 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_required400You asked to copy products from Test to Live with a Test app ID. Use the Live app ID.test_app_required400You asked to copy products from Live to Test with a Live app ID. Use the Test app ID.invalid422One or more fields failed validation. Seeerrorsfor each field. AnIdempotency-Keyheader longer than 255 characters gets this code with400.payment_declined402The payment failed. The provider can also give a more specific reason, listed below.insufficient_funds402The customer's balance is too low.payment_not_approved402The customer declined the prompt on their phone or let it time out.wallet_not_found402The number has no wallet on the network charged, or isn't a valid number.wallet_limit_reached402The customer's wallet reached a transaction or balance limit.wallet_busy402Another payment is already waiting for the customer's approval.network_unavailable402The network can't take this payment now, or can't take it at all on your provider account.amount_too_low402The amount is below the smallest payment your provider takes, so trying again won't help.unauthenticated401The request has no key, or the key is wrong or revoked. Check the Authorization header.forbidden403A 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_unverified403The app is in Live mode and the team owner hasn't verified their email.plan_limit403The request would pass a limit on your plan, such as its number of Live subscribers.plan_read_only403Your plan has made this Live app read-only. Reads still work, and so does charging an invoice.not_found404The 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_taken409Another product in the app already has the slug you sent. Send a different slug.code_taken409Another promotion code in the app already has this code. Codes ignore case, soBLACKFRIDAYandblackfridayare the same. Send a different code.test_app_missing409The app has no Test mode to copy products from.already_paid409The invoice is already paid.invoice_not_open409The invoice is void, for example because the subscription was canceled. You can't create a session to pay it.subscription_canceled409The 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_active409You 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_scheduled409The subscription is already scheduled to cancel, so you can't request a cancel.payment_in_progress409A 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_unavailable409The 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_early409The customer already paid the next period before it started, so an upgrade waits until that period starts. Nothing was charged.session_not_open409The session is already completed or expired, so it can't be expired.idempotency_in_progress409A request with the same Idempotency-Key is still running. Retry after a moment.no_pending_change409The price has no scheduled change to cancel.change_in_effect409The 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.conflict409The request conflicts with the current state of the object.price_archived410The price, or the product it belongs to, is archived, so no new subscription can use it.already_subscribed409At 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_expired410The session expired before the customer submitted their details. The hosted checkout page gets this, not your server. Create a new session.price_not_eligible422The 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_invalid422A discount you sent indiscountscan'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. Theerrorsitem namesdiscounts.promotion_code_invalid422The customer's code is unknown, inactive, expired, used up, or its coupon is no longer valid. Theerrorsitem namescode. 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_applicable422The code's coupon is for other products, or in another currency. Theerrorsitem namescode.promotion_code_amount_too_low422The code's coupon would take the amount below the minimum charge: 100 XAF or XOF, or 50 USD cents. Theerrorsitem namescode.promotion_code_first_time_only422The code is for customers who never paid this app, and this customer has. Theerrorsitem namescode.not_accepting_payments422The 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. Thepaymentsobject on the app says what is missing. An upgrade with something to pay gets this too.payment_unavailable422The payment method isn't offered.phone_required422You asked to charge an invoice, but the customer has no phone number yet. A customer who came through checkout has none until they first pay. Theerrorsitem namesphone_number. Set a number with Update a customer, or send them a payment session, which asks for it. The pay page gets this too when it sends no number for such a customer.idempotency_key_reused422The Idempotency-Key was already used with a different request in the last 24 hours. Use a new key for a new request.webhook_url_missing422You asked to send or resend a webhook, but the app has no webhook URL.rate_limited429Too many requests. See Rate limits.internal500Something went wrong on Abuna's side. Retry later.payment_paused503You asked to charge an invoice, 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_unavailable503The 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.
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.
{
"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.
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"}
}'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
422with codeidempotency_key_reused. - While the first request is still running, it returns
409with codeidempotency_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.
Next steps
- Authentication and API keysAuthenticate requests with your secret key, and know which key goes where.
- Lists and filtersWhat list endpoints return, how to page through and filter them, and how to treat IDs.
- SubscriptionsStart, list, read, update, cancel, keep and change the plan of a customer's subscription.