Error Codes

HashNut API uses standardized error codes to indicate different types of errors. This document provides comprehensive error code reference with meanings, common causes, and resolution steps.

Response Format

Error Response Structure

{
  "code": -2,
  "msg": "Error message description",
  "data": null
}

Response Fields

Field	Type	Description
`code`	integer	Error code (0 = success, non-zero = error)
`msg`	string	Human-readable error message
`data`	object/null	Error details (usually null for errors)

API Response Error Codes

Success Code

`0`: Success ✅

Meaning: Request processed successfully
Common causes: N/A (success state)
Resolution steps: N/A
Example response:

{
  "code": 0,
  "msg": "success",
  "data": {
    "payOrderId": "01KBZ292SK2GKFK97916F5EC3B",
    "accessSign": "D3DE7E4002057C0EAED1BE2268DA53CC9058DCFC9DCAF50D999AF270A7B033C5",
    "merchantOrderId": "e30ff306-5552-497d-9083-fd6e943dfd73"
  }
}

Authentication & Authorization Errors

`-2`: Invalid Signature/Credentials ✅ DOCUMENTED

Meaning: Authentication or signature verification failed. The request signature is invalid, credentials are incorrect, or required authentication headers are missing.
Common causes:
- Invalid API signature (incorrect apiKey used for signing)
- Invalid accessKeyId (merchant access key ID not found or inactive)
- Missing required headers (hashnut-request-uuid, hashnut-request-timestamp, hashnut-request-sign)
- Incorrect signature algorithm implementation
- Invalid currency/chain combination for the merchant account
- Missing or invalid required fields in request body
- API credentials not activated or expired
- IP address restriction (if IP binding is enabled)
Resolution steps:
1. Verify apiKey is correct and matches the one used for signature generation
2. Verify accessKeyId is correct and active in Hashnut dashboard
3. Check that all required headers are present and properly formatted
4. Verify signature generation algorithm matches documentation (HMAC-SHA256, Base64 encoded)
5. Ensure request body JSON string matches exactly what was signed (no extra whitespace, correct field order)
6. Verify the chain/currency combination is supported for your merchant account
7. Check if API key has expired or been deactivated
8. If IP binding is enabled, verify your server's IP address is whitelisted
9. Contact Hashnut support if credentials are confirmed correct but error persists
Example response:

{
  "code": -2,
  "msg": "Invalid signature or credentials",
  "data": null
}

`-1`, `-3`, `-4`: Authentication Errors ⚠️ TO BE CONFIRMED

Meaning: [To be documented by Hashnut team]
Status: These error codes are reserved but meanings need confirmation from Hashnut support
Action: Contact Hashnut support if you encounter these codes

Validation Errors

`-10`, `-11`, `-12`: Parameter Validation Errors ⚠️ TO BE CONFIRMED

Estimated Meaning: Parameter validation errors (likely missing required fields, invalid format, or type mismatches)
Status: Error codes are reserved but exact meanings need confirmation
Common scenarios (estimated):
- Missing required fields in request body
- Invalid chainCode or coinCode format
- Invalid amount format or value
- Invalid merchantOrderId format
- Invalid URL format for callbacks
Resolution steps (general):
1. Verify all required fields are present
2. Check chainCode and coinCode are valid (use config endpoints)
3. Ensure amount is a valid decimal (2 decimal places)
4. Verify merchantOrderId is unique and within length limits (255 chars)
5. Ensure callback URLs are valid HTTPS URLs

Order & Payment Errors

`-20`, `-21`, `-22`, `-23`, `-24`: Order/Payment Errors ⚠️ TO BE CONFIRMED

Estimated Meanings:
- -20: Order creation errors
- -21: Duplicate merchantOrderId
- -22: Invalid amount
- -23: Unsupported chain/coin
- -24: Order not found
Status: Error codes are reserved but exact meanings need confirmation
Resolution steps (general):
- Verify order IDs are correct
- Check if order was created successfully
- Ensure using correct environment (testnet vs production)
- Use unique merchantOrderId for each order
- Verify chain/coin combination is supported

Rate Limiting & Quota Errors

`-30`, `-31`: Rate Limiting Errors ⚠️ TO BE CONFIRMED

Estimated Meaning: Rate limit exceeded or quota exceeded
Status: Error codes are reserved but exact meanings need confirmation
Resolution steps:
1. Check your API usage against rate limits
2. Implement exponential backoff for retries
3. Contact Hashnut support to increase rate limits if needed

System & Server Errors

`-50`, `-51`, `-52`: System Errors ⚠️ TO BE CONFIRMED

Estimated Meanings:
- -50: Internal server error
- -51: Service unavailable
- -52: Database error
Status: Error codes are reserved but exact meanings need confirmation
Resolution steps:
1. Retry the request with exponential backoff
2. Check Hashnut service status
3. Contact Hashnut support if error persists

Business Logic Errors

`-60`, `-61`, `-62`: Business Logic Errors ⚠️ TO BE CONFIRMED

Estimated Meanings:
- -60: Business rule violation
- -61: Insufficient balance/funds
- -62: Account restriction
Status: Error codes are reserved but exact meanings need confirmation
Resolution steps:
1. Review business rules and account status
2. Verify account has sufficient permissions
3. Contact Hashnut support for account-related issues

Network Errors

HTTP Status Codes

Status Code	Description	Resolution
`200`	Success	Request processed successfully
`400`	Bad Request	Check request parameters
`401`	Unauthorized	Verify authentication credentials
`500`	Internal Server Error	Retry request or contact support

Error Handling Best Practices

1. Always Check Response Code

const response = await fetch(url, options);
const result = await response.json();

if (result.code !== 0) {
  // Handle error
  console.error('API Error:', result.msg);
  handleError(result.code, result.msg);
} else {
  // Process success
  processData(result.data);
}

2. Implement Retry Logic

async function makeRequestWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(url, options);
      const result = await response.json();
      
      if (result.code === 0) {
        return result;
      }
      
      // Retry on transient errors
      if (shouldRetry(result.code) && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000); // Exponential backoff
        continue;
      }
      
      throw new Error(result.msg);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await sleep(Math.pow(2, i) * 1000);
    }
  }
}

function shouldRetry(code) {
  // Retry on transient errors (system errors, rate limits), not authentication/validation errors
  // System errors (-50 to -52) and rate limits (-30 to -31) can be retried
  return code <= -30 && code >= -52;
}

3. Provide User-Friendly Messages

function getErrorMessage(code, msg) {
  const errorMessages = {
    '0': 'Success',
    '-2': 'Authentication failed. Please check your API credentials.',
    '-10': 'Validation error. Please check your request parameters.',
    '-11': 'Missing required fields. Please verify all required parameters are included.',
    '-12': 'Invalid parameter format. Please check parameter types and formats.',
    '-20': 'Order creation failed. Please try again or contact support.',
    '-21': 'Duplicate order ID. Please use a unique merchantOrderId.',
    '-22': 'Invalid amount. Please check the payment amount.',
    '-23': 'Unsupported chain or coin. Please verify chainCode and coinCode.',
    '-24': 'Order not found. Please verify the order IDs.',
    '-30': 'Rate limit exceeded. Please slow down your requests.',
    '-31': 'Quota exceeded. Please contact support to increase limits.',
    '-50': 'Internal server error. Please retry or contact support.',
    '-51': 'Service unavailable. Please retry later.',
    '-52': 'Database error. Please contact support.',
    '-60': 'Business rule violation. Please check your account status.',
    '-61': 'Insufficient balance. Please verify account funds.',
    '-62': 'Account restriction. Please contact support.',
  };
  
  return errorMessages[code] || msg || 'An unexpected error occurred';
}

4. Log Errors for Debugging

function handleError(code, msg, context) {
  // Log error with context
  console.error('API Error:', {
    code,
    message: msg,
    context,
    timestamp: new Date().toISOString()
  });
  
  // Send to error tracking service
  errorTrackingService.captureError({
    code,
    message: msg,
    context
  });
}

Payment Validation Error Messages

These error messages appear in the errorMsg field of order responses when payment validation fails. They are returned when querying order status (queryPayOrderWithAccessSign) and indicate why a payment transaction was rejected.

`"amount not enough"` ✅ DOCUMENTED

Meaning: The payment amount received is less than the required order amount
Common causes:
- Customer sent less than the required amount
- Partial payment was made
- Amount calculation error in customer's wallet
Resolution steps:
1. Check the order amount vs. paid amount in the order response
2. If underPaid is true, a supplement order may be available for the remaining amount
3. Customer should send the exact remaining amount to complete payment
4. Verify the amount includes any network fees if required
Example in order response:

{
  "code": 0,
  "msg": "success",
  "data": {
    "state": -1,
    "errorMsg": "amount not enough",
    "amount": 0.01,
    "paidAmount": 0.005,
    "underPaid": true
  }
}

`"coin type mismatch"` or `"coin type not math"` ✅ DOCUMENTED

Meaning: The customer sent the wrong cryptocurrency/token type (e.g., sent USDC instead of USDT)
Common causes:
- Customer selected wrong token in wallet
- Customer sent native coin instead of token (or vice versa)
- Token contract address mismatch
Resolution steps:
1. Verify the order requires the correct coinCode (e.g., "usdt", "usdc")
2. Customer must create a new order with the correct coin type
3. Check that the token contract address matches the order requirements
4. Ensure customer's wallet is configured for the correct token

`"receipt address mismatch"` ✅ DOCUMENTED

Meaning: The payment was sent to a different address than the order's receipt address
Common causes:
- Customer copied wrong address
- Customer sent to a different merchant address
- Address was modified in customer's wallet
Resolution steps:
1. Verify the customer used the exact receiptAddress from the order
2. Check that the address format is correct (case-sensitive for some chains)
3. Customer should verify the address matches before sending
4. If payment was sent to wrong address, it cannot be recovered - customer must create a new order

`"transaction execute failed"` ✅ DOCUMENTED

Meaning: The blockchain transaction failed to execute (e.g., reverted, out of gas, insufficient balance)
Common causes:
- Insufficient gas/energy for transaction
- Smart contract execution reverted
- Insufficient token balance in customer's wallet
- Network congestion causing transaction failure
- Transaction was rejected by the network
Resolution steps:
1. Check the transaction hash on blockchain explorer to see failure reason
2. Verify customer has sufficient balance (token + native coin for gas)
3. Ensure gas limit is sufficient for the transaction
4. Customer should retry the payment with adequate gas
5. Check network status for congestion issues

`"can not parse transaction"` or `"cannot parse transaction"` ✅ DOCUMENTED

Meaning: The system cannot parse or decode the transaction data from the blockchain
Common causes:
- Transaction format is invalid or corrupted
- Unsupported transaction type
- Transaction data encoding issues
- Blockchain node returned malformed data
Resolution steps:
1. Verify the transaction hash is valid on blockchain explorer
2. Check if transaction is confirmed on blockchain
3. Contact Hashnut support with transaction hash for investigation
4. Customer may need to create a new order if transaction cannot be recovered

`"transaction not found"` ✅ DOCUMENTED

Meaning: The transaction hash provided cannot be found on the blockchain
Common causes:
- Transaction hash is incorrect or invalid
- Transaction was never broadcast to the network
- Transaction is still pending and not yet indexed
- Wrong blockchain network (e.g., transaction on testnet but checking mainnet)
Resolution steps:
1. Verify the transaction hash is correct
2. Check the transaction on the correct blockchain explorer for the chain
3. Wait a few minutes if transaction was just sent (may need time to be indexed)
4. Verify the correct network/chain is being checked
5. If transaction truly doesn't exist, customer should retry payment

Payment Amount Scenarios

These are payment status scenarios (not error codes) that appear in order responses:

Underpaid Payment ✅ DOCUMENTED

Meaning: Customer sent less than the required order amount. The system creates a supplement order for the remaining amount.
Indicators in response:
- underPaid: true
- paidAmount field present with amount less than amount
- supplements array contains supplement orders with state: 0 (pending)
Resolution steps:
1. Check paidAmount vs. amount to see the difference
2. Find the active supplement order in supplements array where state === 0
3. Customer should pay the remaining amount to the same receiptAddress
4. After payment, call confirmSupplementPaid API with the supplement's supplementId and transaction hash

Overpayment / Flag Amount ✅ DOCUMENTED

Meaning: Customer sent more than the required amount, or there's a tolerance/adjustment amount (flagAmount) added to the order.
Indicators in response:
- flagAmount field present (non-zero)
- amountString = originalAmountString + flagAmountString
- Payment amount can be >= amountString (original + flag)
Resolution: System accepts payments that are equal to or greater than the adjusted amount

Error Code Reference Table

Code	Status	Category	Retry?	Notes
`0`	✅ Documented	Success	N/A	Request processed successfully
`-2`	✅ Documented	Authentication	❌ No	Invalid signature/credentials
`-1`, `-3`, `-4`	⚠️ To be confirmed	Authentication	❌ No	Reserved, needs confirmation
`-10` to `-12`	⚠️ To be confirmed	Validation	❌ No	Parameter validation errors
`-20` to `-24`	⚠️ To be confirmed	Order/Payment	❌ No	Order/payment errors
`-30` to `-31`	⚠️ To be confirmed	Rate Limiting	⚠️ Yes	Rate limit/quota errors
`-50` to `-52`	⚠️ To be confirmed	System	⚠️ Yes	System/server errors
`-60` to `-62`	⚠️ To be confirmed	Business Logic	❌ No	Business rule violations

Payment Validation Error Messages

Error Message	Status	Notes
`"amount not enough"`	✅ Documented	Payment amount less than required
`"coin type mismatch"`	✅ Documented	Wrong cryptocurrency/token type
`"receipt address mismatch"`	✅ Documented	Payment sent to wrong address
`"transaction execute failed"`	✅ Documented	Blockchain transaction failed
`"can not parse transaction"`	✅ Documented	Cannot parse transaction data
`"transaction not found"`	✅ Documented	Transaction hash not found

Order State Codes

State Code	Status	Notes
`0`	✅ Documented	Unpaid - Order created, awaiting payment
`1`	✅ Documented	Not Completed - Payment initiated
`2`	✅ Documented	Waiting for Blockchain Confirmation
`3`	✅ Documented	Confirming - Transaction confirmed
`4`	✅ Documented	Success - Payment complete and verified
`-1`	✅ Documented	Failed - Payment transaction failed
`-2`	✅ Documented	Expired - Order expired without payment
`-3`	✅ Documented	Cancelled - Order cancelled by merchant

Troubleshooting Common Errors

"Invalid signature or credentials"

Checklist:

apiKey is correct
Request body is stringified correctly (no whitespace)
UUID is unique for each request
Timestamp is in milliseconds
All required headers are present
Signature is Base64 encoded correctly

"Invalid parameters"

Checklist:

All required fields are present
chainCode is valid (use config endpoint to verify)
coinCode is valid and case-sensitive
amount is a valid decimal (2 decimal places)
merchantOrderId is unique
Callback URLs are valid HTTPS URLs

"Order not found"

Checklist:

payOrderId is correct
merchantOrderId matches the order
accessSign is from the order creation response
Using correct environment (testnet vs production)

Getting Help

If you encounter errors not documented here:

Check Logs: Review request/response logs
Verify Configuration: Ensure all settings are correct
Test with cURL: Test API calls directly with cURL
Contact Support:
- Email: support@hashnut.io
- Include error code, message, and request details
- Share relevant logs (without sensitive data)

Next Steps

Review Authentication for signature issues
Check API Endpoints for parameter requirements
Explore Troubleshooting for common issues

Need help? Check out Troubleshooting →

Response Format​

Error Response Structure​

Response Fields​

API Response Error Codes​

Success Code​

0: Success ✅​

Authentication & Authorization Errors​

-2: Invalid Signature/Credentials ✅ DOCUMENTED​

-1, -3, -4: Authentication Errors ⚠️ TO BE CONFIRMED​

Validation Errors​

-10, -11, -12: Parameter Validation Errors ⚠️ TO BE CONFIRMED​

Order & Payment Errors​

-20, -21, -22, -23, -24: Order/Payment Errors ⚠️ TO BE CONFIRMED​

Rate Limiting & Quota Errors​

-30, -31: Rate Limiting Errors ⚠️ TO BE CONFIRMED​

System & Server Errors​

-50, -51, -52: System Errors ⚠️ TO BE CONFIRMED​

Business Logic Errors​

-60, -61, -62: Business Logic Errors ⚠️ TO BE CONFIRMED​

Network Errors​

HTTP Status Codes​

Error Handling Best Practices​

1. Always Check Response Code​

2. Implement Retry Logic​

3. Provide User-Friendly Messages​

4. Log Errors for Debugging​

Payment Validation Error Messages​

"amount not enough" ✅ DOCUMENTED​

"coin type mismatch" or "coin type not math" ✅ DOCUMENTED​

"receipt address mismatch" ✅ DOCUMENTED​

"transaction execute failed" ✅ DOCUMENTED​

"can not parse transaction" or "cannot parse transaction" ✅ DOCUMENTED​

"transaction not found" ✅ DOCUMENTED​

Payment Amount Scenarios​

Underpaid Payment ✅ DOCUMENTED​

Overpayment / Flag Amount ✅ DOCUMENTED​

Error Code Reference Table​

Payment Validation Error Messages​

Order State Codes​

Troubleshooting Common Errors​

"Invalid signature or credentials"​

"Invalid parameters"​

"Order not found"​

Getting Help​

Next Steps​

Response Format

Error Response Structure

Response Fields

API Response Error Codes

Success Code

`0`: Success ✅

Authentication & Authorization Errors

`-2`: Invalid Signature/Credentials ✅ DOCUMENTED

`-1`, `-3`, `-4`: Authentication Errors ⚠️ TO BE CONFIRMED

Validation Errors

`-10`, `-11`, `-12`: Parameter Validation Errors ⚠️ TO BE CONFIRMED

Order & Payment Errors

`-20`, `-21`, `-22`, `-23`, `-24`: Order/Payment Errors ⚠️ TO BE CONFIRMED

Rate Limiting & Quota Errors

`-30`, `-31`: Rate Limiting Errors ⚠️ TO BE CONFIRMED

System & Server Errors

`-50`, `-51`, `-52`: System Errors ⚠️ TO BE CONFIRMED

Business Logic Errors

`-60`, `-61`, `-62`: Business Logic Errors ⚠️ TO BE CONFIRMED

Network Errors

HTTP Status Codes

Error Handling Best Practices

1. Always Check Response Code

2. Implement Retry Logic

3. Provide User-Friendly Messages

4. Log Errors for Debugging

Payment Validation Error Messages

`"amount not enough"` ✅ DOCUMENTED

`"coin type mismatch"` or `"coin type not math"` ✅ DOCUMENTED

`"receipt address mismatch"` ✅ DOCUMENTED

`"transaction execute failed"` ✅ DOCUMENTED

`"can not parse transaction"` or `"cannot parse transaction"` ✅ DOCUMENTED

`"transaction not found"` ✅ DOCUMENTED

Payment Amount Scenarios

Underpaid Payment ✅ DOCUMENTED

Overpayment / Flag Amount ✅ DOCUMENTED

Error Code Reference Table

Payment Validation Error Messages

Order State Codes

Troubleshooting Common Errors

"Invalid signature or credentials"

"Invalid parameters"

"Order not found"

Getting Help

Next Steps