Skip to main content
For field-level messages and common failure modes, see the full Error catalog.

Rules

Store reference_id before executing Always persist your reference_id before calling any execution endpoint. If the HTTP response is lost due to a network error, query the transaction status using this ID before retrying. Never generate a new reference_id unless you have confirmed the original did not result in a transaction. HTTP 422 is a developer error Treat 422 Unprocessable Entity as a signal to fix your request payload. Inspect the detail array for field-level validation messages. PROCESSING is not a failure Mobile money transactions may remain in PROCESSING for several minutes while the carrier confirms the payment. Do not cancel or retry during this window. Refresh your Bearer token proactively Implement a background refresh that obtains a new token when the remaining validity drops below 5 minutes. Expired tokens return HTTP 401. Use prediction endpoints first Call /v1/predictions/amount-and-fees before executing to validate fee calculations and detect FX rate changes before funds move.

Error Response Format

Validation Error (HTTP 422)

The loc array shows the exact field path that failed. loc[0] is always "body" for request body fields.

Authentication Error (HTTP 401)

Obtain a new token via POST /v1/jwt/client/obtain/token and retry.

Retry with Exponential Backoff

For network errors and 5xx responses, implement exponential backoff before retrying.
Python
Node.js

HTTP Status Code Reference


Support & Resources

When contacting support about a specific transaction, always include your reference_id, the full request body, and the HTTP response body.
Last modified on May 22, 2026