Error Handling

Understanding and handling API errors.

HTTP Status Codes

Code	Description
200	Success
400	Bad Request (validation errors)
401	Unauthorized (invalid API key)
403	Forbidden (insufficient balance, IP blocked)
404	Not Found
429	Too Many Requests (rate limit)
500	Internal Server Error
502	Bad Gateway (upstream service unavailable)

Error Response Format

{
    "status": "error",
    "message": "Error description",
    "data": null
}

Common Error Messages

Error Message	HTTP Code	Description	Solution
API key is required	401	Missing X-Api-Key header	Include X-Api-Key header in request
Invalid API key	401	API key invalid or expired	Check API key in dashboard
IP address not allowed	403	Request IP not in whitelist	Add IP to whitelist or disable IP restrictions
Insufficient balance	403	Account balance too low	Add funds to your account
Order not found	404	Order doesn't exist or doesn't belong to user	Verify order ID and ownership
Product not found	404	Product/variant doesn't exist	Check product availability
Product out of stock	400	Product unavailable	Choose different product or wait
Validation failed	400	Invalid input parameters	See validation errors in response
Too Many Requests	429	Rate limit exceeded	Implement exponential backoff
Upstream service unavailable	502	Laravel backend unreachable	Retry after a few seconds

Validation Errors

Validation errors return 400 Bad Request with specific field errors:

{
    "status": "error",
    "message": "Validation failed",
    "data": {
        "errors": {
            "quantity": ["The quantity must be at least 1"],
            "link": ["The link field is required"],
            "player_id": ["The player_id must be 10 digits"]
        }
    }
}

Handling Rate Limits

When you receive a 429 Too Many Requests response:

1. Wait before retrying (implement exponential backoff)
2. Reduce request frequency
3. Cache responses where appropriate

Example backoff strategy:

• First retry: Wait 1 second
• Second retry: Wait 2 seconds
• Third retry: Wait 4 seconds
• Continue doubling up to a maximum (e.g., 60 seconds)

Balance Refunds

If an order fails, your balance is automatically refunded. No manual action required.

Best Practices

1. Always Check Status Codes

const response = await fetch(url, options);

if (!response.ok) {
    if (response.status === 429) {
        // Rate limit - wait and retry
        await sleep(1000);
        return retry();
    } else if (response.status === 401) {
        // Invalid API key - notify user
        throw new Error('Invalid API key');
    } else if (response.status === 403) {
        const error = await response.json();
        if (error.message.includes('balance')) {
            // Insufficient balance
            throw new Error('Please add funds to your account');
        }
    }
}

const data = await response.json();

2. Validate Before Submitting

Use validation endpoints before placing orders:

• Free Fire: POST /api/freefire/check-player
• PUBG: POST /api/pubg/check-player
• Internet: GET /api/internet/check-number/{type}/{number}

3. Handle Timeouts

Orders are processed asynchronously. If a request times out:

• Save the order ID/transaction ID if received
• Poll the status endpoint to check completion
• Don't retry immediately without checking status first

4. Monitor Balance

Check balance before placing large orders:

const balance = await fetch('/api/balance', {
    headers: { 'X-Api-Key': apiKey }
}).then(r => r.json());

if (balance.data.available_balance < orderCost) {
    throw new Error('Insufficient balance');
}

5. Log Errors for Debugging

try {
    const result = await placeOrder(data);
} catch (error) {
    console.error('Order failed:', {
        endpoint: '/api/freefire/order',
        request: data,
        error: error.message,
        timestamp: new Date().toISOString()
    });
    throw error;
}

Support

If you encounter persistent errors:

1. Check your API key and IP whitelist settings
2. Verify you have sufficient balance
3. Review this error documentation
4. Contact support with:
   • Timestamp of the error
   • Request details (without sensitive data)
   • Error message received
   • Order ID (if applicable)

Contact support through the WASMOU Dashboard.