Skip to main content

​
Error Codes

This page documents all error codes returned by the 123hub API, along with their meanings and recommended handling strategies.

​
Error Response Format

Error responses return HTTP 400 (or HTTP 404 for unknown methods). The error object contains a numeric code, a human-readable message, and optional details and context fields (both null by default). 
{
  "success": false,
  "error": {
    "code": 6010,
    "message": "Payment does not exist",
    "details": null,
    "context": null
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "processing_time": 5
}
Successful responses return HTTP 200. Error responses return HTTP 400 (most errors) or HTTP 404 (unknown method). Always check the success field in the response body to determine whether the request succeeded or failed.

​
Error Code Categories

Error codes are grouped into categories by their numeric range:
RangeCategoryDescription
1xxxSystem errorsInternal server errors, service unavailability, rate limits, timeouts
2xxxMethod routing errorsUnknown or invalid method value in request body
3xxxAuthentication errorsSignature verification, application ID, and access issues
4xxxProvider/routing errorsProvider account or route configuration issues
5xxxLimit errorsCustomer or transaction limit violations
6xxxPayment errorsPayment creation, lookup, status, and amount issues
7xxxExternal provider errorsErrors returned by or timeouts from external payment providers
8xxxParsing errorsMalformed request body
9xxxValidation errorsMissing or invalid field values

​
Complete Error Code Reference

CodeMessageHTTP StatusDescription
1000Common error400Unexpected server error
1001Endpoint not found400The requested endpoint does not exist
1002The method does not exist / is not available404The method field contains an unknown value
1005Invalid request format400A required field is missing or the request is malformed
1006Invalid Content-Type header400Content-Type must be application/json
1007HTTP Method Not Allowed400Only POST is supported
2001Unexpected error400An unexpected processing error occurred
2002The payment provider is not available400No available route for the given service_id
3000Authentication error400General authentication failure (e.g., incorrect X-Data-Hash)
3001Missing / incorrect X-Data-Application-Id header400The X-Data-Application-Id header is missing or malformed
3002Missing / incorrect X-Data-Hash header400The X-Data-Hash header is missing
3003The app does not exist400No application found for the given X-Data-Application-Id
3004The app is disabled400Your application has been disabled
3005The app is blocked400Your application has been blocked
6001Incorrect transaction amount400Amount is zero, negative, or otherwise invalid
6002Incorrect currency code400Currency does not match the expected currency for the service_id
6004Insufficient funds400Not enough balance for this withdrawal
6009Payment already exists400Duplicate c_id for this merchant
6010Payment does not exist400No payment found with given identifiers
7001Error of interaction between payment provider and payment system400External provider returned an error
7002Payment provider not available400External provider did not respond in time
8801Current payment or operation status does not allow this action400Invalid status transition
9000Validation error400Generic validation failure

​
Error Details by Category

​
System Errors (1xxx)

These errors indicate problems on the server side. Most are transient and can be retried. 1000 — Common error An unexpected error occurred. Retry with exponential backoff. 
{
  "success": false,
  "error": {
    "code": 1000,
    "message": "Common error",
    "details": null,
    "context": null
  },
  "request_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "processing_time": 12
}
1001 — Endpoint not found The requested endpoint does not exist. Verify your URL. 1002 — Method not available (HTTP 404) The method field in the request body does not match any supported method. Supported methods: payment.in, payment.out, payment.status, balance.get, gateway.ping. This is the only error that returns HTTP 404 instead of 400. 
{
  "success": false,
  "error": {
    "code": 1002,
    "message": "The method does not exist / is not available.",
    "details": null,
    "context": null
  },
  "request_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
  "processing_time": 2
}
1005 — Invalid request format A required field is missing or the request body is malformed. The details field contains a description of the issue. 
{
  "success": false,
  "error": {
    "code": 1005,
    "message": "Invalid request format",
    "details": {
      "description": "missing required properties including: 'payer'. Path: $.params.payment"
    },
    "context": null
  },
  "request_id": "d4e5f6a7-b8c9-0123-defa-234567890123",
  "processing_time": 3
}
1006 — Invalid Content-Type header Content-Type must be application/json. 1007 — HTTP Method Not Allowed Only POST is supported.

​
Routing Errors (2xxx)

2001 — Unexpected error An unexpected processing error occurred during request routing. 2002 — Payment provider not available No available route was found for the given service_id. This may mean the service is not configured or has been deactivated. Contact support.

​
Authentication Errors (3xxx)

These errors relate to the X-Data-Application-Id and X-Data-Hash headers. 3000 — Authentication error General authentication failure. The SHA512 hash in X-Data-Hash does not match the expected value. Verify your hashing algorithm and secret key. 3001 — Missing / incorrect X-Data-Application-Id header The X-Data-Application-Id header is missing or malformed. 3002 — Missing / incorrect X-Data-Hash header The X-Data-Hash header is missing. 3003 — The app does not exist No application found for the given X-Data-Application-Id. 3004 — The app is disabled Your application has been disabled. Contact support. 3005 — The app is blocked Your application has been blocked. Contact support.

​
Payment Errors (6xxx)

6001 — Incorrect transaction amount The amount is zero, negative, or otherwise invalid. 
{
  "success": false,
  "error": {
    "code": 6001,
    "message": "Incorrect transaction amount",
    "details": null,
    "context": null
  },
  "request_id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "processing_time": 8
}
6002 — Incorrect currency code The currency does not match the expected currency for the service_id. 6004 — Insufficient funds Not enough balance for this withdrawal. Check your balance using the balance.get method. 6009 — Payment already exists A payment with the same c_id already exists for this merchant. Use a unique c_id for each payment, or query the existing payment using payment.status. 6010 — Payment does not exist No payment was found with the provided identifiers (c_id, h_id, or p_id).

​
External Provider Errors (7xxx)

7001 — Provider interaction error The external payment provider returned an error. This may be transient. Retry after a delay or contact support if it persists. 7002 — Payment provider not available The external provider did not respond within the expected time. Retry the request.

​
Status Errors (8xxx)

8801 — Invalid status transition The requested action cannot be performed because the payment is in a status that does not allow it (e.g., trying to cancel a completed payment).

​
Validation Errors (9xxx)

9000 — Validation error Generic validation failure. The details field may indicate the specific issue.

​
Error Handling Best Practices

Check the success field

Always check success in the response body. Do not rely on HTTP status codes for error detection.

Use request_id for debugging

Log the request_id from every response. Include it when contacting support.

Retry transient errors

Implement exponential backoff for error codes 1000, 7001, and 7002.

Validate before sending

Validate inputs client-side before making API calls to avoid 1005 and 9000 errors.

​
Example Error Handler

const BASE_URL = "https://api.123hub.pro/public/api/multihub/v1";

async function makeApiRequest(body) {
  const response = await fetch(BASE_URL, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "X-Data-Application-Id": "12345",
      "X-Data-Hash": computeSha512Hash(body),
    },
    body: JSON.stringify(body),
  });

  const data = await response.json();

  if (!data.success) {
    const { code, message } = data.error;

    if (code >= 1000 && code < 2000) {
      // System error — retry with exponential backoff
      console.error(`System error ${code}: ${message}`);
      await retryWithBackoff(() => makeApiRequest(body));
    } else if (code >= 3000 && code < 4000) {
      // Auth error — check credentials
      console.error(`Auth error ${code}: ${message}`);
      throw new AuthenticationError(message);
    } else if (code >= 6000 && code < 7000) {
      // Payment error — handle business logic
      console.error(`Payment error ${code}: ${message}`);
      throw new PaymentError(code, message);
    } else if (code >= 7000 && code < 8000) {
      // Provider error — retry or escalate
      console.error(`Provider error ${code}: ${message}`);
      await retryWithBackoff(() => makeApiRequest(body));
    } else if (code >= 9000) {
      // Validation error — fix request
      console.error(`Validation error ${code}: ${message}`);
      throw new ValidationError(message, data.error.details);
    } else {
      throw new ApiError(code, message);
    }
  }

  return data;
}