Logo GenukaGenuka Pay
Guides

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

Validation or Application Error
{
  "message": "Error description",
  "errors": {
    "field": ["Error message"]
  }
}

Common HTTP Statuses

CodeMeaning
400Malformed or invalid business input
401Missing or invalid authentication
403Request blocked: incomplete company profile, card payments not enabled, KYC not done, or a dashboard-only action
404Resource not found
422Validation failure, or a payment the operator or provider refused — the message says why
500Internal server error
503Provider 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

Authentication Error
{
  "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

403
{
  "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.

Validation Error
{
  "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
  1. always log external_id, track_id, request route, and response code together
  2. distinguish validation failures from retryable provider failures
  3. retry only when the failure is clearly transient
  4. never blindly retry KYC or limit-related refusals
  5. 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