XPayLabs API Error Handling — Codes, Causes, and Solutions

XPayLabs returns structured error responses with HTTP status codes. Learn about common error scenarios, validation failures, and how to handle them gracefully.

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