Error Handling

FinovoPay uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, 4xx range indicate an error from the provided information (e.g., a required parameter was omitted), and 5xx range indicate an error with our servers.

HTTP Status Codes

Code	Meaning	Description
200	OK	Everything worked as expected.
400	Bad Request	The request was unacceptable, often due to missing parameters.
401	Unauthorized	No valid API key provided.
402	Request Failed	The parameters were valid but the request failed (e.g., Insufficient funds).
500, 502, 504	Server Errors	Something went wrong on FinovoPay's end or with the banking network.

Error Response Body

JSON Error Payload

{
  "success": false,
  "error": {
    "type": "invalid_request_error",
    "code": "parameter_missing",
    "message": "The 'amount' parameter is required for this action.",
    "param": "amount"
  }
}

Troubleshooting Tip

Always log the full JSON error response during development. The message field usually contains specific details about why a banking transaction was declined or why a BVN verification failed.