DevelopersVirtual AccountError Codes
Error Codes
All KongaPay Virtual Account API errors return a consistent JSON structure.
Error Response Structure
Error Response
{
"status": "error",
"message": "A duplicate reference already exists.",
"code": 409
}Error Reference
| HTTP Status | Code | Error | Resolution |
|---|---|---|---|
| 400 | — | Bad Request | Check request body for missing or malformed fields. |
| 400 | — | Missing secretKey | Include your secretKey in the request header. |
| 401 | — | Unauthorized | Your secretKey is invalid. Contact support to verify or rotate your key. |
| 404 | — | Account Not Found | No settlement account found for your integration. Contact support. |
| 404 | — | Transaction Not Found | No record exists for this reference. Verify the value and retry. |
| 409 | — | Duplicate Reference | A virtual account with this reference already exists. Use a new reference. |
| 409 | 94 | Pending Transaction | Payment is still processing. Wait and retry with exponential backoff. |
Error Handling Tips
400Validation Errors
- →Check all required fields are present
- →Verify field types match the spec
- →Confirm secretKey header is included
401Auth Errors
- →Ensure you're using the correct environment's key
- →Contact KongaPay support to rotate keys
- →Never log or expose your secretKey
404Not Found
- →Verify the reference value is correct
- →Check your settlement account is set up
- →Confirm you're using the right base URL
409Conflicts
- →Generate a new unique reference for duplicates
- →Use exponential backoff for pending (code 94)
- →Store references server-side before API calls