Pool Sell

This document provides a comprehensive guide to all possible errors that can be returned exclusively from the /pool/sell API endpoint. Use this guide to understand error responses and how to handle them in your application.

Note: This document only includes error codes that are returned by the Pool Sell API endpoint. Some error codes may be shared with other transaction APIs, but the context and handling described here are specific to Pool Sell transactions.

Error Response Format

All errors are returned in the following JSON format:

{
  "errors": [
    {
      "code": <error_code>,
      "text": "<error_message>"
    }
  ]
}

Important: For internal server errors (5xx), the error code and message are masked for security:

• Error Code: Always 499999
• Error Message: Always "Something went wrong!"

The original error details are logged server-side for debugging purposes.

---

Error Categories

1. Client Errors (400 Bad Request)

These errors indicate issues with the request format or validation.

1.1 Invalid Request Format

• HTTP Status: 400 Bad Request
• Error Code: 400001
• Error Message: "missing or invalid parameters"
• What it means: The request body is malformed, missing required fields, or contains invalid data types.
• How to fix:
  • Verify your JSON structure is valid
  • Ensure all required fields are present
  • Check that field types match the API specification (e.g., amounts are numbers, not strings)

1.2 Unsupported Currency Pair

• HTTP Status: 400 Bad Request
• Error Code: 402001
• Error Message: "unsupported currency pair"
• What it means: The currency pair is not supported for pool sell transactions. This can occur when:
  • The crypto currency symbol provided in the request is not found or not supported in the system
  • The currency pair (crypto to fiat combination) is not enabled for pool sell transactions, even if the crypto symbol itself is valid
  • The specific combination of crypto_symbol and fiat_symbol is not allowed
• How to fix:
  • Verify the crypto_symbol field contains a valid and supported cryptocurrency symbol (e.g., "USDT", "BTC")
  • Check that the currency symbol matches the exact format expected by the API
  • Ensure the cryptocurrency is enabled for pool sell transactions
  • Verify that the currency pair (crypto_symbol to fiat_symbol) is supported for pool sell
  • Contact support if you believe the currency or currency pair should be supported

1.3 Invalid Request Data

• HTTP Status: 400 Bad Request
• Error Code: 403001
• Error Message: "invalid request"
• What it means: The request contains invalid data that doesn't meet business rules. This error can occur in several scenarios:
  • Zero or negative crypto amounts: The crypto_amount field is zero or negative
  • Invalid payment method for PHP: PHP currency transactions with invalid payment method configurations
  • Fiat payment initiation failures: Errors during fiat payment creation, including:
    • Missing or invalid source_id (payment instrument ID)
    • Invalid bank account UUID
    • Payment method validation failures
• How to fix:
  • Verify all amounts are positive numbers greater than zero
  • Ensure transaction amounts meet minimum requirements
  • Check that source_id is provided and is a valid UUID for a bank account or payment instrument
  • Verify payment method is valid for the selected currency
  • Ensure all required parameters are provided with valid values

---

2. Authorization Errors (403 Forbidden)

These errors indicate that the request is valid but cannot be processed due to authorization or business rule violations.

2.1 Invalid User

• HTTP Status: 403 Forbidden
• Error Code: 405001
• Error Message: "invalid user for this client"
• What it means: The user associated with the request doesn't exist or doesn't belong to the specified client.
• How to fix:
  • Verify the user ID is correct
  • Ensure the user exists in the system
  • Confirm the user belongs to the correct client

2.2 Pool Transactions Not Enabled

• HTTP Status: 403 Forbidden
• Error Code: 406002
• Error Message: "pool transactions not enabled for client"
• What it means: Pool sell transactions are not configured or enabled for this client.
• How to fix:
  • Contact support to enable pool transactions for your client
  • Verify that pool transactions are available for your account
• Note: This error code is specific to Pool Sell API and indicates pool configuration issues.

2.3 Pool Transaction Not Allowed

• HTTP Status: 403 Forbidden
• Error Code: 406001
• Error Message: "pool transaction not allowed for this user"
• What it means: The user attempting the transaction is the same as the pool user, which is not allowed.
• How to fix:
  • Ensure the transaction is initiated by a different user than the pool user
  • Verify user permissions and pool configuration
• Note: This error code is specific to Pool Sell API and indicates a pool user conflict.

2.4 Insufficient Pool Balance

• HTTP Status: 403 Forbidden
• Error Code: 403002
• Error Message: "insufficient balance"
• What it means: The pool user doesn't have sufficient balance in the specified cryptocurrency to complete the transaction. In Pool Sell, balance is checked against the pool user's wallet, not the requesting user's wallet.
• How to fix:
  • Check the pool user's balance for the requested cryptocurrency
  • Reduce the transaction amount
  • Ensure the pool has sufficient funds before initiating the transaction
• Note: While this error code is shared with other APIs, in Pool Sell it specifically refers to the pool user's balance, not the requesting user's balance.

2.5 Transaction Limits Exceeded

• HTTP Status: 403 Forbidden
• Error Code: 404001
• Error Message: "limits validation failed for the transaction"
• What it means: The transaction exceeds configured limits (daily, monthly, or per-transaction limits).
• How to fix:
  • Check your transaction limits
  • Reduce the transaction amount
  • Wait until the limit period resets
  • Contact support if you need to increase your limits

---

---

4. Internal Server Errors (500 Internal Server Error)

These errors indicate problems on the server side. The error code and message are masked for security.

Note: Currency-related errors (invalid currency symbols or currency IDs not found in database) are now handled as internal server errors (error code 499999) rather than "Not Found" errors, as they indicate data integrity issues that should be investigated server-side.

4.1 Generic Server Error

• HTTP Status: 500 Internal Server Error
• Error Code: 499999
• Error Message: "Something went wrong!"
• What it means: An unexpected error occurred on the server. This is a catch-all error for various internal issues.
• How to fix:
  • Retry the request after a short delay
  • If the error persists, contact support with:
    • The transaction ID (if available)
    • The timestamp of the request
    • The request payload (without sensitive data)
  • Check system status page for known issues

---

Error Handling Best Practices

1. Retry Logic

• Do retry for 500 Internal Server Error (error code 499999)
  • Use exponential backoff (e.g., wait 1s, 2s, 4s before retries)
  • Limit retries to 3-5 attempts
  • Don't retry for client errors (4xx)

2. Error Code Handling

• 400-499 errors: These are client errors - fix your request before retrying
• 500 errors: These are server errors - safe to retry with backoff
• 499999: Generic server error - always retry with backoff

3. User-Friendly Messages

• Map technical error codes to user-friendly messages in your UI
• Provide actionable guidance based on error codes
• Log detailed error information for debugging

4. Monitoring and Alerting

• Monitor error rates, especially for 499999 errors
• Set up alerts for high error rates
• Track which error codes occur most frequently

---

Quick Reference: Error Codes

---

Common Scenarios

Scenario 1: Unsupported Currency Pair

Error: 400 Bad Request with code 402001

Solution: Verify the crypto_symbol is valid and supported. Check that the cryptocurrency symbol matches the exact format expected (e.g., "USDT", "BTC"). Ensure the currency pair (crypto_symbol to fiat_symbol) is supported for pool sell transactions. Contact support if you believe the currency or currency pair should be supported.

Scenario 2: Insufficient Balance

Error: 403 Forbidden with code 403002

Solution: Check pool balance and reduce transaction amount

Scenario 3: Limits Exceeded

Error: 403 Forbidden with code 404001

Solution: Check transaction limits and wait for reset or reduce amount

Scenario 4: Pool Not Configured

Error: 403 Forbidden with code 406002

Solution: Contact support to enable pool transactions

Scenario 5: Invalid Currency (Internal Error)

Error: 500 Internal Server Error with code 499999

Solution: Verify currency symbols are correct and supported. If the error persists, contact support as this may indicate a data integrity issue.

Scenario 6: Server Error

Error: 500 Internal Server Error with code 499999

Solution: Retry with exponential backoff, contact support if persists

Scenario 7: Invalid Source ID

Error: 400 Bad Request with code 403001

Solution: Ensure source_id is provided in the request body and is a valid UUID for a bank account or payment instrument. Verify the payment instrument exists and belongs to the user.

---

Support

If you encounter errors that aren't covered in this guide, or if errors persist after following the recommended fixes, please contact support with:

1. Error Details:
   • HTTP status code
   • Error code
   • Error message
   • Request timestamp
2. Request Information:
   • Transaction ID (if available)
   • User ID
   • Currency symbols
   • Transaction amount
3. Context:
   • Steps to reproduce
   • Frequency of occurrence
   • Any relevant logs or error traces

---

Version Information

• API Version: Current
• Last Updated: [Current Date]
• Document Version: 1.0
• API Endpoint: /pool/sell