Docs: Errors & Limits

API errors and limits

Errors and Rate Limits

All error responses follow the same shape. Use the status code to handle them.

200

OK

Request succeeded.

400

Bad Request

The request is malformed or unsupported, such as an unsupported country code.

401

Unauthorized

Missing or invalid API key.

422

Unprocessable Content

Validation failed. Check required fields, field lengths, and formats.

429

Too Many Requests

Daily rate limit hit. Resets every 24 hours.

500

Server Error

Something went wrong on our end. Try again in a moment.

401 example

{
  "statusCode": 401,
  "message": "Invalid API key."
 }

422 example

{
  "message": "Validation failed",
  "errors": [
    {
      "field": "accountNumber",
      "errors": ["accountNumber must be exactly 10 digits"]
    }
  ],
  "error": "Unprocessable Entity",
  "statusCode": 422
 }

429 example

{
  "statusCode": 429,
  "message": "Daily limit of 20 account resolutions reached. Resets in ~18 hours."
 }
The resolve endpoint allows 20 requests per API key per 24 hours. The banks endpoint has no daily limit. Bank data is aggressively cached so requests rarely hit Flutterwave.

Correct the request before retrying

A validation error requires a change to the submitted fields, not repeated requests with the same body. Compare the field names, required values and account-number format with the endpoint reference. For an authentication failure, check the API-key header and key status. Show a useful message to your user without exposing the key or full banking details. A successful HTTP response still needs to be read according to the endpoint's documented data shape.

Handle limits and temporary failures

When account resolution reaches its daily allowance, stop automatically repeating the call and let the user know they must try later. Avoid making a request on every keystroke: wait for complete details and an intentional submission. For temporary server or network errors, use a bounded retry with a delay rather than an unlimited loop. Retain enough context to troubleshoot the status code and endpoint, while leaving secrets and sensitive account information out of application logs.