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: incomplete company profile, card payments not enabled, KYC not done, or a dashboard-only action |
404 | Resource not found |
422 | Validation failure, or a payment the operator or provider refused — the message says why |
500 | Internal server error |
503 | Provider unreachable, timed out or overloaded: retry later with the same Idempotency-Key |
Payment errors are never answered with 502: a 502 you receive comes from the network in front of the API, not from Genuka Pay.
Common Failure Shapes
Invalid Authentication
{
"message": "Unauthenticated."
}A bad signature, a timestamp more than 5 minutes off, an unknown or inactive public key: all of them produce this same 401. Check the signed string first (see Authentication).
Incomplete Company Profile
{
"message": "Your company profile must be completed before you can access this resource.",
"code": "COMPANY_PROFILE_INCOMPLETE",
"missing_fields": ["legal_type"]
}Complete the profile from the dashboard; the integration endpoints answer this way until it is done.
Validation Failure
HTTP 422. message repeats the first error; errors lists every invalid field.
{
"message": "The payer phone field format is invalid.",
"errors": {
"payer_phone": ["The payer phone field format is invalid."]
}
}Payment Status Check Errors
GET /api/v1/payments/status/{track_id} reports operator-side errors as {"error": "...", "error_code": "..."} (TRANSACTION_NOT_FOUND, CHECK_STATUS_ERROR) instead of message. See Payments API.
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?
Last updated on