API Reference
Log In
API Reference

Error handling

Overview

This document provides guidelines for handling errors in the API. It covers the different types of errors, their corresponding HTTP status codes, and best practices for retrying requests.

Error Types

Errors in the API fall into several categories, each representing a different type of problem. The error types are used to classify issues and determine the appropriate handling mechanism.

Error Types and Descriptions

  • AIRTIME_ERROR: Indicates a failure in processing airtime transactions.
  • AUTHENTICATION_ERROR: Indicates an issue with user authentication.
  • AUTHORIZATION_ERROR: Indicates that a user does not have permission to perform an action.
  • BANK_ERROR: General bank-related errors.
  • CACHE_ERROR: Indicates a failure in cache retrieval or storage.
  • COMMUNITY_ERROR: Indicates an issue with community-related operations.
  • CONFIGURATION_ERROR: Indicates a misconfiguration in the system.
  • CURRENCY_ERROR: Indicates a problem with currency operations.
  • DELETION_ERROR: Indicates a failure in deletion operations.
  • GENERAL_ERROR: General error for unspecified issues.
  • EXCHANGE_RATE_ERROR: Indicates a failure in retrieving or applying exchange rates.
  • MOBILE_MONEY_ERROR: Indicates a failure in processing mobile money transactions.
  • MULTICURRENCY_ERROR: Indicates an issue with multi-currency transactions.
  • PAYMENT_ERROR: Indicates a failure in processing payments.
  • PROFILE_ERROR: Indicates an issue with profile retrieval or updates.
  • RESOURCE_NOT_FOUND: Indicates that the requested resource cannot be located.
  • SERVER_ERROR: Indicates unexpected and general server error for unspecified server issues.
  • SEARCH_ERROR: Indicates a problem with search functionalities.
  • SIMULATION_ERROR: Indicates a failure in simulation operations.
  • TRANSACTION_ERROR: Indicates a failure in processing transactions.
  • VOUCHER_ERROR: Indicates a problem with vouchers.
  • VALIDATION_ERROR: Indicates a failure in input validation.
  • WALLET_ERROR: Indicates an issue with wallet-related transactions.

Error Status Codes

The following status codes are used in response to different error types:

  • 400 Bad Request: The request was unacceptable, often due to missing or invalid parameters. Used for errors like AIRTIME_ERROR, BANK_ACCOUNT_ERROR, COMMUNITY_ERROR, CURRENCY_ERROR, MOBILE_MONEY_CODE_ERROR, MULTICURRENCY_ERROR, PAYEE_ERROR, PAYMENT_ERROR, PROFILE_ERROR, SEARCH_ERROR, SIMULATION_ERROR, TRANSACTION_ERROR, TRANSACTION_STATUS_ERROR, VOUCHER_ERROR, VALIDATION_ERROR, WALLET_ERROR.
  • 401 Unauthorized: No valid API key provided. Used for AUTHENTICATION_ERROR.
  • 403 Forbidden: The API key doesn’t have permissions to perform the request. Used for AUTHORIZATION_ERROR.
  • 404 Not Found: The requested resource cannot be located. Used for RESOURCE_NOT_FOUND.
  • 409 Conflict: The request conflicts with another request. Used for DELETION_ERROR.
  • 500 Internal Server Error: An unexpected server-side error occurred. Used for errors like BANK_ERROR, CACHE_ERROR, CONFIGURATION_ERROR, EXCHANGE_RATE_ERROR, INTERNAL_ERROR, MOBILE_MONEY_ERROR, SERVER_ERROR.

Handling Errors

Content Errors (4xx)

Content errors are due to invalid content in the API request. These errors are indicated by HTTP status codes in the 4xx range. For example, a 400 Bad Request indicates a problem with the request's content. Clients should correct the request and retry.

Network Errors

Network errors result from connectivity issues between the client and server, such as socket timeouts or connection terminations. Clients should retry such requests.

Server Errors (5xx)

Server errors are caused by issues on the server side. These errors are indicated by HTTP status codes in the 5xx range. Requests that return a 500 Internal Server Error should be treated as indeterminate. The response may not reflect the final state of the operation, so clients should handle retries carefully and expect possible reconciliation on the server side.

GET and DELETE Requests

GET and DELETE requests are idempotent by nature and can be safely retried without additional idempotency handling.

Generating Idempotency Keys

Idempotency keys should be unique and unambiguous. Common strategies include using UUIDs or deriving keys from unique user-attached objects, such as transaction IDs.

HTTP Status Code Reference

  • 200 OK: Everything worked as expected.
  • 400 Bad Request: The request was unacceptable, often due to missing or invalid parameters.
  • 401 Unauthorized: No valid API key provided.
  • 402 Request Failed: The parameters were valid but the request failed.
  • 403 Forbidden: The API key doesn’t have permissions to perform the request.
  • 404 Not Found: The requested resource cannot be located.
  • 409 Conflict: The request conflicts with another request.
  • 429 Too Many Requests: Too many requests hit the API too quickly. Implement exponential backoff.
  • 500 Internal Server Error: An unexpected server-side error occurred.
  • 502 Bad Gateway: The server received an invalid response from an upstream server.
  • 503 Service Unavailable: The server is currently unavailable (overloaded or down for maintenance).
  • 504 Gateway Timeout: The server did not receive a timely response from an upstream server.