Errors & Error Codes

This page explains the possible error responses that can occur when using the HUCH services for authentication, payments, and payouts.

---

Error response format

Most error responses follow this structure:

{
  "message": "Invalid parameters"
}

Validation errors may include per-field details:

{
  "message": "Invalid parameters",
  "details": {
    "field_name": ["Error description"]
  }
}

Note: The structure of error responses may vary depending on the situation. Always branch on the HTTP status code first and treat message as human-readable text for logs and support — do not pattern-match on it in code.

---

Correlating an error with our logs

Every request and response carries an X-Request-ID header.

• If you send X-Request-ID, we propagate your value end-to-end across our services.
• If you do not, we generate one and return it on the response.

X-Request-ID: 7f9c2b1e-5a44-4c0f-9d3e-2b8a11d6e401

Log this value alongside every API call. Quoting it when you contact support lets us trace the exact request through the whole platform.

---

Retry guidance

HTTP status	Meaning	Safe to retry?
400	Invalid or missing parameters	No — fix the request first
401	Invalid or expired credentials / access token	Yes, once, after obtaining a new access token
403	Action not allowed for this merchant	No — contact your account manager
404	Resource does not exist	No
409	Conflict (e.g. subscription already exists)	No
500, 502, 503, 504	Temporary server or upstream error	Yes, with exponential backoff

Rules of thumb

• Only retry idempotent operations automatically. GET requests (payment details, payout details, webhook details) are always safe to retry.
• Do not blindly retry POST /api/payment/. A retry can create a second payment. If a payment creation call times out or returns a 5xx, first look the payment up by your own order_ref before creating another one.
• Use exponential backoff with jitter — for example 1s, 2s, 4s, 8s — and cap the number of attempts.
• A 5xx does not always mean the operation failed. It may have succeeded server-side before the response was lost, so verify state before retrying a write.
• Never treat a failed status call as a failed payment. Poll again, or rely on webhook notifications as the primary source of status changes.

---

Authentication errors

These errors occur when access or identification fails.

Error code	Meaning
400	Access Token missing / Invalid Parameters
401	Invalid user credentials
404	User doesn't exist
500	Internal error

---

Payment errors

These errors may occur during a payment process.

Error code	Meaning
400	"Invalid Access Token : Wrong number of segments"
403	Forbidden
500	The requested payment could not be found or processed

A 500 error may occur when the requested payment reference does not exist or when the system is unable to retrieve the payment information.

---

Payout errors

These errors may occur during a payout process.

Payout creation

Error code	Meaning
400	Invalid or missing information
403	Action not allowed

Payout status

Error code	Meaning
400	Invalid request
403	Forbiden
404	Not found

Note: Some errors may depend on external factors or temporary service issues.