Error Responses

The BLOX API uses standard HTTP status codes and returns detailed error information in JSON format to help you understand and handle errors effectively.

Error Format

All error responses follow this consistent structure:


{
  "error": {
    "code": "error_code",
    "message": "Human-readable error description",
    "details": "Additional context (optional)"
  }
}

HTTP Status Codes

400 Bad Request

Invalid request parameters or malformed JSON:


{
  "error": {
    "code": "invalid_request",
    "message": "The request is missing required parameters",
    "details": "source_currency is required"
  }
}

401 Unauthorized

Your API key is missing or invalid:


{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key"
  }
}

403 Forbidden

Your API key doesn’t have permission to access the requested resource:


{
  "error": {
    "code": "forbidden",
    "message": "Insufficient permissions for this operation"
  }
}

404 Not Found

The requested resource doesn’t exist:


{
  "error": {
    "code": "not_found",
    "message": "Resource not found"
  }
}

429 Too Many Requests

Rate limit exceeded:


{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Please try again later.",
    "retry_after": 60
  }
}

500 Internal Server Error

An unexpected error occurred on our end:


{
  "error": {
    "code": "internal_error",
    "message": "An internal error occurred. Please try again later."
  }
}

Common Error Codes

Code	Description	Action
`invalid_request`	Request parameters are invalid	Check request format and required fields
`unauthorized`	API key is invalid or missing	Verify your API key
`forbidden`	Insufficient permissions	Check your API key permissions
`not_found`	Resource doesn’t exist	Verify the resource ID or endpoint
`rate_limit_exceeded`	Too many requests	Wait and retry after the specified time
`insufficient_funds`	Account has insufficient balance	Add funds to your account
`invalid_signature`	Request signature is invalid	Check your signature generation
`expired_quote`	Quote has expired	Request a new quote

Error Handling Best Practices

1. Always Check Status Codes


const response = await fetch('/api/endpoint');
if (!response.ok) {
  const error = await response.json();
  console.error('API Error:', error.error.message);
}

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);
      if (response.ok) return response;
      
      if (response.status === 429) {
        const error = await response.json();
        const retryAfter = error.error.retry_after || 60;
        await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
        continue;
      }
      
      throw new Error(`HTTP ${response.status}`);
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      await new Promise(resolve => setTimeout(resolve, 1000 * Math.pow(2, i)));
    }
  }
}

3. Log Errors Appropriately


function handleApiError(error) {
  // Log for debugging
  console.error('API Error:', {
    code: error.error.code,
    message: error.error.message,
    timestamp: new Date().toISOString()
  });
  
  // Show user-friendly message
  showUserMessage(getUserFriendlyMessage(error.error.code));
}

Testing Error Responses

You can test error handling by making requests with invalid parameters:


# Test invalid API key
curl https://api.sandbox.blox.my/v1/health \
  -H "blox-api-key: invalid_key"
 
# Test missing required parameter (requires signature for POST)
curl -X POST https://api.sandbox.blox.my/v1/checkout \
  -H "blox-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Support

If you encounter errors that aren’t covered in this documentation:

Email: support@blox.my
GitHub: github.com/Blox-My