Errors

Every non-2xx response from the Hexolus Payment Gateway shares one envelope:

{
  "message": "human-readable description",
  "code": "machine-readable enum"
}

The envelope may also carry these optional fields:

This page documents:

• The error envelope
• Error code reference
• HTTP status mapping
• Idempotency conflicts
• Debugging 422 validation errors

The error envelope

Always parse code (machine) first; the message field is meant for human display and may evolve. The Content-Type is always application/json for errors emitted by Hexolus's own code; an upstream load balancer or CDN returning a 502 may yield HTML, so check Content-Type defensively.

{
  "message": "notional_minor must be > 0",
  "code": "validation"
}

Error code reference

Codes not listed above are present in Hexolus's internal taxonomy (ip_not_allowed, domain_taken, transfer_locked, auth_code_invalid, insufficient_balance, ineligible_registrant) but are emitted only by internal domain / billing flows and will not appear on the payment gateway public API. If you ever do see one, treat it as an internal_error.

HTTP status mapping

The mapping is deterministic and exhaustive:

If you write a generic error handler, switching on code is more forward-compatible than switching on HTTP status.

Tenancy and 404

Hexolus deliberately does not distinguish "this resource does not exist" from "this resource exists but belongs to another tenant". Both surface as 404 not_found. This prevents enumeration attacks where a caller could otherwise learn which IDs are in use across the platform by counting 403s vs 404s.

This applies to:

• GET /v1/payments/{id}
• POST /v1/payments/{id}/cancel
• GET /v1/settlements/{id}

If you are confident the ID was minted by your own client and you receive a 404, the most likely cause is a typo or a misrouted environment (production ID against staging or vice versa).

Idempotency conflicts

The Idempotency-Key header on POST /v1/payments is not a uniqueness constraint that returns 409 conflict. Instead:

• A second POST with the same key and an otherwise-identical body is treated as a retry and returns the original payment (HTTP 200 or 201).
• A second POST with the same key but different body fields still returns the original payment — Hexolus does not compare bodies. This means a buggy client that reuses the key across distinct orders will return the wrong record without erroring.

The practical implication: choose Idempotency-Key values that are provably unique per logical request (e.g. order-{your_uuid}, order-{date}-{seq}). If your key generator might collide, you will silently receive someone else's payment instead of a clean 409.

If you genuinely need to detect a collision client-side, store the (idempotency_key, payment_id) pair locally and reject any reuse before sending the request.

Debugging 422 validation errors

A 422 validation response always includes a message that names the failed rule:

{
  "message": "channel_code required for method virtual_account",
  "code": "validation"
}

For form-style endpoints (admin and a subset of client API surfaces), an additional field_errors block points at the offending field(s):

{
  "message": "request body is invalid",
  "code": "validation",
  "field_errors": {
    "amount": ["must be > 0"],
    "channel_code": ["unsupported value: \"BCASYARIAH\""]
  }
}

Common 422 causes on the payments API:

For anything still unclear, copy the full response (including the X-Hexolus-Delivery-Id header if from a webhook) and contact support — Hexolus retains request logs for 14 days.