While standard HTTP status codes effectively describe response failures, in certain situations, it's beneficial to delve deeper to distinguish and pinpoint specific causes of failures, especially when the HTTP status code is overly ambiguous.
Introducing error codes: these enums are included in JSON response bodies specifically crafted to offer detailed contextual information about failures. They serve as a method to facilitate seamless and programmatic error handling on the client side, empowering your application to comprehend and respond effectively to various failure scenarios.
LOOKUP_ACCOUNT_NOT_FOUND (HTTP 404)
Specific to the lookup operation, returned when the provided account identifier couldn't be looked up. This could occur for various reasons. For instance, the account number is invalid, or, even if the account number appears syntactically correct, it may not be registered with the intended banking entity, or we couldn't retrieve the metadata in realtime (in such case try again in 5 minutes).
IDEMPOTENCY_RACE (HTTP 409)
When two or more requests are being sent with the same idempotency key concurrently, Only the winning request in the race will be processed, while the others will receive a response containing this error code. See idempotency
IDEMPOTENCY_KEY_ALREADY_USED (HTTP 409)
In the very unlikely scenario when our server is unable to cache a response for idempotency and a client will re-attempt the request, to prevent re-executing the request, this error will be returned. If you ever experience this error you should contact our customer service support.
WALLET_INSUFFICIENT_BALANCE (HTTP 402)
Specific to the send money operation, when trying to transfer money from a wallet that lacks the required balance.
PAYOUT_BANK_TEMPORARILY_UNAVAILABLE (HTTP 503)
Specific to the creat payout/send money operation, returned when the recipient bank is not currently available for the specified country. (e.g. The receiving bank is experiencing some technical issue and currently not able to accept payouts.)
PAYOUT_MOBILE_MONEY_TEMPORARILY_UNAVAILABLE (HTTP 503)
Specific to the creat payout/send money operation, returned when the recipient mobile money operator is not currently available for the specified country. (e.g. The receiving operator is experiencing some technical issue and currently not able to accept payouts.)
VALIDATION_FAILED (HTTP 422)
Although the JSON document's structure (or query string) is syntactically correct, one or more of its properties may be invalid concerning the specific resource. For instance, it could be a phone number that doesn't adhere to the specified format.
Example
{
"code": "VALIDATION_FAILED",
"message": "Validation failed.",
"errors": {
"fields": {
"email_address": [
"email_address is a required field",
"must be a valid e-mail address"
]
}
}
}