Skip to content
ABUNA
DocsErrors

Getting started

Errors

Status codes, error codes, field errors, rate limits, request IDs, and how to retry safely.

View as Markdown

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
{
  "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)
{
  "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 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_json400

    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_required400

    You asked to copy products from Test to Live with a Test app ID. Use the Live app ID.
  • test_app_required400

    You asked to copy products from Live to Test with a Live app ID. Use the Test app ID.
  • invalid422

    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_declined402

    The payment failed. The provider can also give a more specific reason, listed below.
  • insufficient_funds402

    The customer's balance is too low.
  • payment_not_approved402

    The customer declined the prompt on their phone or let it time out.
  • wallet_not_found402

    The number has no wallet on the network charged, or isn't a valid number.
  • wallet_limit_reached402

    The customer's wallet reached a transaction or balance limit.
  • wallet_busy402

    Another payment is already waiting for the customer's approval.
  • network_unavailable402

    The network can't take this payment now, or can't take it at all on your provider account.
  • amount_too_low402

    The amount is below the smallest payment your provider takes, so trying again won't help.
  • unauthenticated401

    The request has no key, or the key is wrong or revoked. Check the Authorization header.
  • forbidden403

    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_unverified403

    The app is in Live mode and the team owner hasn't verified their email.
  • plan_limit403

    The request would pass a limit on your plan, such as its number of Live subscribers.
  • plan_read_only403

    Your plan has made this Live app read-only. Reads still work, and so does charging an invoice.
  • not_found404

    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_taken409

    Another product in the app already has the slug you sent. Send a different slug.
  • code_taken409

    Another promotion code in the app already has this code. Codes ignore case, so BLACKFRIDAY and blackfriday are the same. Send a different code.
  • test_app_missing409

    The app has no Test mode to copy products from.
  • already_paid409

    The invoice is already paid.
  • invoice_not_open409

    The invoice is void, for example because the subscription was canceled. You can't create a session to pay it.
  • subscription_canceled409

    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_active409

    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_scheduled409

    The subscription is already scheduled to cancel, so you can't request a cancel.
  • payment_in_progress409

    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_unavailable409

    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_early409

    The customer already paid the next period before it started, so an upgrade waits until that period starts. Nothing was charged.
  • session_not_open409

    The session is already completed or expired, so it can't be expired.
  • idempotency_in_progress409

    A request with the same Idempotency-Key is still running. Retry after a moment.
  • no_pending_change409

    The price has no scheduled change to cancel.
  • change_in_effect409

    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.
  • conflict409

    The request conflicts with the current state of the object.
  • price_archived410

    The price, or the product it belongs to, is archived, so no new subscription can use it.
  • already_subscribed409

    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_expired410

    The session expired before the customer submitted their details. The hosted checkout page gets this, not your server. Create a new session.
  • price_not_eligible422

    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_invalid422

    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_invalid422

    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_applicable422

    The code's coupon is for other products, or in another currency. The errors item names code.
  • promotion_code_amount_too_low422

    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_only422

    The code is for customers who never paid this app, and this customer has. The errors item names code.
  • not_accepting_payments422

    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 says what is missing. An upgrade with something to pay gets this too.
  • payment_unavailable422

    The payment method isn't offered.
  • phone_required422

    You 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. The errors item names phone_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_reused422

    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_missing422

    You asked to send or resend a webhook, but the app has no webhook URL.
  • rate_limited429

    Too many requests. See Rate limits.
  • internal500

    Something went wrong on Abuna's side. Retry later.
  • payment_paused503

    You 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_unavailable503

    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.

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

Next steps