Error Handling
HTTP Status Codes & Errors
HivePay uses standard HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, 4xx indicate client-side errors, and 5xx indicate provider or server issues.
HTTP Status Code Reference
| Status Code | Meaning | Description |
|---|---|---|
| 200 OK | Success | The request was accepted and processed successfully. |
| 400 Bad Request | Invalid Payload | Malformed JSON or missing required parameter fields. |
| 401 Unauthorized | Missing / Bad API Key | Missing or invalid X-API-Key header. |
| 402 Payment Required | Insufficient Balance | Wallet balance is insufficient to cover the requested payout amount (the service fee is cut from that amount). |
| 422 Unprocessable | Validation Error | Phone number invalid, amount outside limits (500 to 5,000,000 UGX), etc. |
| 500 Server Error | Gateway Issue | Internal service or upstream network failure. Retry with backoff. |
Standard Error Response JSON
When an error occurs, HivePay returns a standardized JSON object with a detailed descriptive message:
422 Validation Error Example
{
"success": false,
"error": "Validation Error",
"message": "The amount field must be between 500 and 5000000.",
"errors": {
"amount": [
"The amount field must be between 500 and 5000000."
]
}
}
401 Unauthorized Example
{
"success": false,
"message": "Unauthorized. Invalid or missing X-API-Key header."
}