Limits & quotas

Four different ceilings can refuse the same call, and each one answers with a different status code. Reading the code tells you which one you hit before you read anything else.

Plan quotas are a fifth kind, and they refuse the resource rather than the amount: payment links and invoices stop being creatable once the plan's allowance is used.

Amounts, per currency

One table governs both directions. POST /payments and POST /transfers read the same per-currency bounds, so a payout is refused by exactly the figures that would refuse a payment of the same size. Amounts are in major units.

Ninety-two currencies carry bounds, not only the ones above. A currency absent from that table is not bounded at all at this layer, and the account limits further down are then the only ceiling.

Out of bounds, the call never reaches a provider.

422 on a 10 XAF payment

{

"code": 422,

"status": "Unprocessable Entity",

"message": "Amount must be between 25 and 2000000 XAF.",

"errors": {

"amount": [

"The amount must be between 25 and 2000000 XAF."

]

}

}

The same refusal on POST /transfers reads Transfer amount must be between …, with the same two figures.

One mobile money debit is capped separately

The currency ceiling is what a payment may be worth. The mobile money ceiling is what a single debit on a wallet may be worth, and it is far lower.

A mobile money charge above that cap is refused at processing time, not at creation. The payment stays pending and can be retried.

422 on a 900,000 XAF mobile money charge

{

"code": 422,

"status": "Unprocessable Entity",

"message": "This transaction amount exceeds the per-transaction limit for cm.mtn. Use split_count or split_amounts to split the payment.",

"payer_message": "This amount is above the limit for this payment method."

}

Splitting a payment into two to four charges is documented here. Today the instalment executor runs in sandbox, so treat the cap as a hard ceiling in live and size the charge under it.

What your account is allowed to move

Above the per-call bounds sit six figures attached to your team: a single, daily and monthly ceiling for money in, and the same three for money out. They are written by compliance verification, not by your plan.

Those are base figures in XAF, and nobody gets them as written. Four multipliers apply on top, and they compound.

A verified low-risk company therefore runs at 1.5 × 1.2 × 1.5 = 2.7 times the base, while an individual trader under review runs at zero.

Once the ceiling is real, breaching it reads as a decline.

402 on a payment above the single-transaction ceiling

{

"code": 402,

"status": "Payment Required",

"error_code": "limit_exceeded",

"message": "Transaction amount 1 200 000 XAF exceeds your single-transaction limit of 500 000 XAF. Please contact support to increase your limit.",

"payer_message": "This payment could not be completed. Please try a smaller amount or contact the merchant."

}

The daily and monthly counters run on credited live payments in that currency, and reset at midnight UTC and on the first of the month. Payout counters count pending, processing, review and succeeded transfers together, so a payout held for review still occupies the day's allowance.

Funds are held before they can be withdrawn

A credited payment lands in pending_balance and moves to available_balance when its hold elapses. The base hold follows the rail the money came in on.

Your risk level scales that base by 0.5, 1, 2 or 3, and the result is clamped between 6 and 168 hours. A team with an explicit ops override skips the scaling entirely.

Payouts have their own brakes

Three mechanisms sit between a payout request and the money leaving, and they are independent of the amount ceilings above.

A held payout is not a failed one: it sits in review and moves on once approved. Treat review as a normal state in your reconciliation rather than an error.

Plan quotas

The plan governs resources and throughput, never amounts.

Link and invoice allowances count live rows only, and creating past them answers 403. Sandbox links and invoices are free.

Requests per minute

Four counters run on every call, and the first to trip wins. They are not alternatives: a request under the team ceiling can still be refused by the IP one.

Endpoint ceilings are a base figure times a plan multiplier.

Rate limits carries the response headers and the two 429 body shapes.

Field limits

Validation bounds you are most likely to hit, all from the request rules themselves.

Webhook delivery

Answer inside the timeout or the delivery is retried, which is why acknowledging first and processing after is the shape to build.