Errors

Being released

The money rails described here are built and tested, and are being rolled out. Until a rail is switched on for the exchange, invoices are paid by bank transfer or mobile money and recorded by Finance, as today.

Every refusal has the same shape: a machine-readable error code and a message a person can read.

{ "error": "invoice_not_owed", "message": "INV-0002 is paid; nothing is owed on it" }

A request that does not fit the endpoint's schema is a 400 with the list of problems:

{ "error": "bad_request", "issues": [{ "path": ["amountMinor"], "message": "Expected number, received string" }] }

Status codes

Status	Meaning
200 / 201	Done; 201 when something was created
202	Accepted: a payment out was opened and waits for approvals or for the provider
400	The request is malformed (bad_request, bad_phone, bad_document, …)
401	No valid session (unauthorized), or a webhook with a bad signature (bad_signature)
403	Signed in, without the role this write needs (forbidden, with roles)
404	No such record (not_found)
409	The request is understood, but the record's state does not allow it
422	Driver KYC details the card processor would refuse (kyc_incomplete, with problems)
429	Too many wrong passwords (too_many_attempts, with retryAfterSeconds)
503	A ledger, rail or provider did not answer (ledger_unavailable, rail_unavailable, …)

Money codes

Code	Meaning
currency_not_on_rail	The record's currency is not one this rail carries (no conversion)
rail_not_configured	That rail is not switched on for this exchange
rail_unavailable	The rail did not answer; try again
transfer_open	A payment for this record is already open: approve or cancel it first
not_awaiting_approval	The transfer is not waiting for approvals
already_approved	You already approved this transfer; a different user must give the second approval
not_cancellable	Only a payment out that has not been sent can be cancelled
invoice_not_owed	The invoice is not Issued or Part-paid
overpayment	More than is outstanding on the invoice
not_a_bill_to_collect	A freight invoice is paid by the exchange, not collected
not_ours_to_pay	Only a freight invoice is paid out by the exchange
no_stellar_address	The party has no Stellar address on record
no_trustline	The recipient's Stellar account cannot hold that coin yet
no_wallet	The party has no Celo wallet on record
no_phone	No phone on record to pay or to collect from
no_funding_source	Nothing records where the escrow's money came from
card_refund_by_hand	A card-funded escrow is refunded through Mamlaka
invalid_amount	Mobile money is whole shillings; B2C is at least KES 10
test_numbers_only	In the gateway sandbox only its test numbers are allowed
gateway_refused	Mamlaka refused the request; the message says why
cards_not_configured	Virtual cards are not switched on for this exchange
kyc_not_approved	A card is issued only once the driver's KYC is approved
kyc_in_hand	KYC is waiting or approved; only a rejected one is resubmitted
card_not_active	The card is pending, frozen or closed
not_issued_here	The card was not issued through the exchange
trip_not_in_transit	A card is loaded only for a trip on the road
float_too_low	Mamlaka's float cannot cover the issue or load

Ledger codes

Code	Meaning
ledger_refused	The receipt contract refused the change; the contract's own reason is in the message, and nothing was written
ledger_unavailable	The chain did not answer
lot_not_on_ledger	The lot has no token on the ledger yet
insufficient_stock	More than is available on the lot or listing
over_capacity / warehouse_suspended	The warehouse cannot take it