XPayLabs API Error Handling — Codes, Causes, and Solutions

XPayLabs returns errors using a standard R<T> envelope with an HTTP-compatible code and a human-readable msg. Unlike traditional payment processors, XPayLabs errors are primarily validation and authentication errors — since blockchain transactions are final, there are no “card declined” or “insufficient funds” errors at the API level (those are blockchain-level issues).

Error Response Format

{
  "code": 400,
  "msg": "The amount cannot be left blank.",
  "data": null
}

Field	Type	Description
`code`	integer	HTTP-compatible status code
`msg`	string	Human-readable error description
`data`	null	Always `null` in error responses

Status Codes

Code	Meaning	Typical Cause
`400`	Bad Request	Missing or invalid parameters
`401`	Unauthorized	Invalid HMAC signature or expired timestamp
`422`	Unprocessable	Invalid address format for chain
`429`	Too Many Requests	Rate limit exceeded
`500`	Internal Error	Unexpected gateway error

Common Validation Errors

Signature Errors (`401`)

Message	Cause
`"The sign cannot be left blank."`	`sign` field is missing from the request
`"Sign verification failed"`	HMAC signature doesn’t match computed value
`"The timestamp cannot be left blank."`	`timestamp` is missing
`"The nonce cannot be left blank."`	`nonce` is missing

Order Errors (`400`)

Message	Cause
`"The amount cannot be left blank."`	Amount is missing or null
`"The symbol cannot be left blank."`	Token symbol is missing
`"The chain cannot be left blank."`	Blockchain network is missing
`"The receiveAddress cannot be left blank."`	Payout destination address is missing
`"ReceiveAddress error"`	Address format is invalid for the specified chain
`"The orderId cannot be left blank."`	Required for V3 merchants
`"The uid cannot be left blank."`	Required for V2 merchants
`"The uid cannot be zero."`	uid is set to `"0"`

Handling Errors in Your Integration

async function createCollection(payload) {
  const response = await fetch("http://your-gateway:3010/v1/order/createCollection", {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });

  const result = await response.json();

  if (result.code !== 200) {
    switch (result.code) {
      case 401:
        // Signature issue — recompute sign and retry
        console.error("Auth error:", result.msg);
        break;
      case 400:
        // Validation error — fix request parameters
        console.error("Validation error:", result.msg);
        break;
      case 429:
        // Rate limited — back off and retry
        await sleep(1000);
        return createCollection(payload);
      default:
        console.error("Unexpected error:", result.msg);
    }
    return null;
  }

  return result.data;
}

Rate Limiting

XPayLabs enforces configurable rate limits per endpoint. Exceeding the limit returns a 429 response. Default limits:

Endpoint	Limit
`/order/createCollection`	100 req / 10s per IP
`/order/createPayout`	100 req / 10s per IP
`/order/status/{orderId}`	1000 req / 10s
`/order/pay`	2 req / 1s per orderId
`/order/getOrderStatus`	2 req / 1s per orderId
`/symbol/supportSymbols`	50 req / 10s

Documentation Index

​Error Response Format

​Status Codes

​Common Validation Errors

​Signature Errors (401)

​Order Errors (400)

​Handling Errors in Your Integration

​Rate Limiting