When you make an API request, errors can occur due to authentication failures, invalid input, or processing issues. It's important to handle these errors properly by understanding their structure, status codes, and related messages. You can explore the details below.

Error Structure

If there’s an issue with your request, the API returns a 4XX or 5XX HTTP status code along with a structured error response. This response includes information about what went wrong.

{
    "status": "failed",
    "error": {
        "type": "REQUEST_NOT_VALID",
        "code": "10400",
        "message": "Request is not valid",
        "validation_errors": [
            {
                "field_name": "payment_method_id",
                "message": "must not be null"
            },
            {
                "field_name": "currency",
                "message": "must not be null"
            }
        ]
    }
}

The general structure of the error contains:

General Error Codes

When a request fails, it returns an error code to help identify the issue and guide troubleshooting. Below is a list of common error codes, their meanings, and potential causes:

Collections or Inflow Payments Error Codes

Below is a list of error codes you may encounter when collecting payments. If you keep getting persistent errors, please contact our support team for assistance.

Payout Error Codes

Transfers could fail for different reasons. Read all possible error codes for payouts in the table below:

Handling Timeout Errors

In some cases, requests may timeout if there is no feedback from our servers within a period of time (usually between 25 and 28 seconds). This typically applies to charge and order requests. If you encounter a timeout with another service API, please contact our support team for assistance.

When this happens, we return a requires_requery with an HTTP 201 Created status. This indicates that the charge is being processed and should not be retried.

{
    "status": "success",
    "message": "Charge created",
    "data": {
        "id": "chg_ZWf4Kiifxx",
        "amount": 250,
        ....
        "next_action": {
            "type": "requires_requery",
            "requires_requery": {}
        },
        "payment_method_details": {
            ...
        },
       ..
        "status": "pending",
        ...
        "created_datetime": "2026-05-14T13:33:15.625Z"
    }
}

When you receive this response, wait 20 seconds before calling the retrieve charge/order endpoints to fetch the updated next_action object.

{
    "status": "success",
    "message": "Charge fetched",
    "data": {
        "id": "chg_tSn4fdwdwR",
        "amount": 250,
         ...    
        "next_action": {
            "type": "redirect_url",
            "redirect_url": {
                "url": "https://developersandbox.flutterwave.com/redirects?bank_account&token=eyJhbGciOiJIUzI1NiJ9.eyJjbGllbnRJZCI6IjQ0OTllNjBiLThkYzgtNDdlMy05ZDYyLWQwOTUyNjA1ZTYyOSIsImNoYXJnZUlkIjoiY2hnX3RTbjRmZHdkd1IiLCJzdWIiOiI0NDk5ZTYwYi04ZGM4LTQ3ZTMtOWQ2Mi1kMDk1MjYwNWU2MjkiLCJpYXQiOjE3NzkyMjY5MzAsImV4cCI6MTc3OTIyNzIzMH0.lnGvyF4_kWIPW_G0-qWWV1jwGeD0anmsqkXdKN58tSc"
            }
        },
        "payment_method_details": {
            "type": "bank_account",
            "bank_account": {},
            "id": "pmd_f5hpfzTraH",
            "meta": {},
            "created_datetime": "2026-05-19T21:41:57.493Z"
        },
        "redirect_url": "https://flutterwave.com/",
        "reference": "TRN-vL11q2TcVqhc",
        "status": "pending",
        "processor_response": {
            "type": "pending",
            "code": "02"
        },
        "created_datetime": "2026-05-19T21:42:10.654Z"
    }
}

If the retrieve request still returns a requires_requery response, retry the request in 40 seconds. Transactions that remain unresolved after a minute will transition to a failed status.

To safely retry a request, add the X-Idempotency-Key header to your request to prevent duplicate transactions.

curl --request POST \
--url 'https://developersandbox-api.flutterwave.com/charges' \
--header 'Authorization: Bearer {{ACCESS TOKEN}}' \
--header 'Content-Type: application/json' \
--header 'X-Idempotency-Key: {{X_IDEMPOTENCY_KEY}}' \
--data '{
   "reference": "TRN-64OVUUz9Tul7",
   "currency": "USD",
   "customer_id": "cus_9zKqBW94OP",
   "payment_method_id": "pmd_gZvoGry0vq",
   "redirect_url":"https://flutterwave.com/",
   "amount": 250,
   "meta":{
     "person_name": "Derek Jones",
     "role": "Developer"
   }
 }'

Rate Limiting

We rate-limit every API endpoint to keep the platform stable and fast for everyone building on it. When these limits are exceeded, the API returns an HTTP 429 Too Many Requests response. In some cases, intermediary infrastructure such as CDNs, WAFs, or traffic protection services may return non-JSON responses (for example, HTML error pages such as Cloudflare 1015 responses) before requests reach the API origin.

Rate limits may be enforced using a combination of signals: API credentials, account identifiers, IP addresses, request volume, and concurrent request behaviour. Your integration should ensure that both request throughput and concurrent in-flight requests remain within supported limits.

The current limit is 500 API requests per minute.

Managing Rate Limits

Rate limiting should be considered as part of your service architecture and traffic management strategy. These practices reduce the likelihood of rate limiting in systems:

1. Design workflows to minimise unnecessary API calls.
2. Use caching and batching where appropriate to reduce the frequency of requests.
3. Implement idempotency to prevent duplicates during retries.
4. Always use webhooks and event-driven integrations instead of aggressive polling (this should only be considered as a last resort).
5. Limit request concurrency and avoid unbounded parallel processing patterns.
6. Ensure your application gracefully handles non-JSON error responses returned by intermediary systems.

Retry Strategy

If you receive an HTTP 429 Too Many Requests response or intermediary throttling responses such as Cloudflare 1015, implement a controlled retry strategy:

1. Stop sending immediate follow-up requests after throttling occurs.
2. Retry requests using exponential backoff with randomized jitter. For example, wait 1s, then 2s, then 4s, adding a small random offset each time so retries from multiple clients don't sync up.
3. Increase the delay gradually with each attempt.
4. Set retry limits to avoid infinite retry loops.
5. Avoid high-frequency polling or uncontrolled concurrent retries that may continue triggering restrictions.

Retries may help recover from temporary traffic bursts. Repeated rate-limit responses usually indicate that request patterns, concurrency levels, or polling strategies should be redesigned.