Error Handling
Handle validation, authentication, provider, and business-rule failures cleanly.
Introduction
Your integration should treat Genuka Pay responses as operational signals, not just HTTP transport results. A clean implementation distinguishes validation failures, business refusals, and retryable upstream issues.
Validation Errors
Reject malformed payloads early and surface user-safe messages in your product.
Business Refusals
Treat KYC, limit, or policy failures as operational decisions, not retry candidates.
Retryable Failures
Retry transient provider or infrastructure issues with idempotency and clear correlation IDs.
Typical Error Envelope
{
"message": "Error description",
"errors": {
"field": ["Error message"]
}
}Common HTTP Statuses
| Code | Meaning |
|---|---|
400 | Malformed or invalid business input |
401 | Missing or invalid authentication |
403 | Request blocked or not permitted |
404 | Resource not found |
422 | Validation failure |
500 | Internal server error |
502 | Upstream or provider-side failure |
Common Failure Shapes
Invalid Authentication
{
"message": "No application found."
}Validation Failure
{
"message": "Validation failed",
"errors": {
"amount": ["The amount must be at least 100"]
}
}KYC or Limit Refusal
Payment or payout initiation can fail when compliance status or transaction limits prevent execution.
Treat these as business failures that may require:
- user or merchant notification
- account review
- KYC completion or escalation
- internal support follow-up
Recommended Handling Strategy
- always log
external_id,track_id, request route, and response code together - distinguish validation failures from retryable provider failures
- retry only when the failure is clearly transient
- never blindly retry KYC or limit-related refusals
- keep asynchronous reconciliation separate from the request-response path
Operational recommendation
Use idempotency, request correlation, and webhook reconciliation together. Error handling should not stop at the first HTTP response when the underlying operation is asynchronous.
How is this guide?