Error Handling

The Web3 Portal API uses conventional HTTP response codes and returns detailed error information in a consistent JSON format.

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "message": "Human-readable error message",
  "errors": null
}

For validation errors, the errors field contains field-specific error messages:

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "The amount field is required."
    ],
    "network": [
      "The network must be either erc20 or trc20."
    ]
  }
}

Response Fields

Field	Type	Description
success	boolean	Always false for errors
message	string	Human-readable error description
errors	object|null	Field-specific validation errors (for 422 responses) or null

HTTP Status Codes

Code	Status	Description
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request format
401	Unauthorized	Authentication failed
403	Forbidden	Insufficient permissions
404	Not Found	Resource not found
409	Conflict	Business logic conflict
422	Unprocessable Entity	Validation failed
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error
502	Bad Gateway	External provider error
503	Service Unavailable	Service under maintenance

Common Errors

Authentication Errors (401)

Unauthenticated

{
  "success": false,
  "message": "Unauthenticated. Please provide valid credentials.",
  "errors": null
}

Causes:

• API key not provided in request headers
• API key doesn't exist or has been deactivated
• Wrong API key provided

Solutions:

• Ensure you're including the X-API-Key or Api-Key header
• Verify your API key is correct and active
• Generate a new API key if needed

Authorization Errors (403)

IP Address Not Authorized

{
  "success": false,
  "message": "This API key is not authorized from your IP address.",
  "errors": null
}

Causes:

• Your request IP is not in the API key's allowed IP list

Solutions:

• Add your IP address to the allowed list in merchant portal
• Remove IP restrictions if not needed

Validation Errors (422)

{
  "success": false,
  "message": "Validation failed",
  "errors": {
    "amount": [
      "The amount field is required.",
      "The amount must be at least 0.01."
    ]
  }
}

Common validation rules:

• amount: Required, numeric, minimum 0.01
• currency: Optional, must be one of the supported currencies
• memo: Optional, maximum 255 characters
• out_trade_no: Optional, string up to 255 characters, unique per merchant

Business Logic Errors (409)

Duplicate Order ID

{
  "success": false,
  "message": "The provided out_trade_no already exists for this merchant.",
  "errors": null
}

Solution: Use a unique out_trade_no per order.

Rate Limiting (429)

{
  "success": false,
  "message": "Too many requests. Please slow down.",
  "errors": null
}

Solutions:

• Wait before retrying (see Rate Limiting)
• Implement exponential backoff
• Cache responses when possible

Server Errors (500, 502, 503)

Internal Server Error

{
  "success": false,
  "message": "An error occurred while processing your request.",
  "errors": null
}

Solutions:

• Retry with exponential backoff
• Contact support if issue persists

External Provider Error

{
  "success": false,
  "message": "Payin service is unavailable. Please try again later.",
  "errors": null
}

Solutions:

• Retry after a few seconds
• Contact support if issue persists

Basic Error Handling

try {
  const response = await axios.post(url, data, {
    headers: { 'X-Api-Key': apiKey }
  });
  return response.data;
} catch (error) {
  if (error.response) {
    const status = error.response.status;
    const message = error.response.data.message;
    
    if (status === 429) {
      // Rate limited - wait and retry
      await sleep(5000);
      return retry();
    }
    
    if (status >= 500) {
      // Server error - retry with backoff
      return retryWithBackoff();
    }
    
    // Client error - log and handle
    console.error('API Error:', status, message);
    throw error;
  }
  throw error;
}