​
Error Response Format

All API errors follow a consistent format:

{
  "status": "error",
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": {
      // Additional error details
    }
  },
  "code": 400 // HTTP status code
}

​
HTTP Status Codes

The Bila API uses conventional HTTP status codes to indicate the success or failure of an API request:

Status CodeDescription
200 - 299Success - The request was successfully received, understood, and accepted
400Bad Request - The request was invalid or cannot be served
401Unauthorized - Authentication is required and has failed or not been provided
403Forbidden - The request is understood but has been refused or access is not allowed
404Not Found - The requested resource could not be found
422Unprocessable Entity - The request was well-formed but was unable to be followed due to semantic errors
429Too Many Requests - The user has sent too many requests in a given amount of time
500 - 599Server Error - Something went wrong on our end

​
Common Error Codes

  • invalid_request: The request is missing required parameters or contains invalid parameters.
  • authentication_failed: The API key provided is invalid or has been revoked.
  • insufficient_funds: The wallet or account does not have sufficient funds to complete the transaction.
  • resource_not_found: The requested resource does not exist.
  • rate_limit_exceeded: The API rate limit has been exceeded.

​
Handling Errors

Here’s an example of how to handle errors in your code:

async function makeApiRequest() {
  try {
    const response = await fetch('https://api.usebila.com/v1/resource', {
      headers: {
        'Authorization': 'Bearer YOUR_API_KEY',
        'Content-Type': 'application/json'
      }
    });
    
    const data = await response.json();
    
    if (!response.ok) {
      // Handle error based on status code and error message
      handleApiError(data, response.status);
      return null;
    }
    
    return data;
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

function handleApiError(errorData, statusCode) {
  const { error } = errorData;
  
  switch (statusCode) {
    case 400:
      console.error(`Bad Request: ${error.message}`);
      // Handle validation errors
      break;
    case 401:
      console.error(`Authentication failed: ${error.message}`);
      // Redirect to login or refresh token
      break;
    case 403:
      console.error(`Forbidden: ${error.message}`);
      // Handle permission issues
      break;
    case 404:
      console.error(`Not Found: ${error.message}`);
      // Handle resource not found
      break;
    case 429:
      console.error(`Rate Limited: ${error.message}`);
      // Implement backoff strategy
      break;
    default:
      console.error(`API Error (${statusCode}): ${error.message}`);
      // Handle other errors
      break;
  }
}

​
Validation Errors

For validation errors (typically 400 Bad Request), the API will return detailed information about what went wrong:

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "Validation failed",
    "details": {
      "amount": ["Amount must be greater than 0"],
      "currency": ["Currency is required"]
    }
  },
  "code": 400
}

​
Best Practices

  1. Always check for errors: Never assume that an API request will succeed.

  2. Log errors: Log errors for debugging and monitoring purposes.

  3. Provide user-friendly messages: Translate API error messages into user-friendly messages.

  4. Implement retry logic: For transient errors (like network issues or rate limits), implement retry logic with exponential backoff.

  5. Handle specific error codes: Implement specific handling for different error codes.

​
Idempotency

To prevent duplicate transactions, the Bila API supports idempotency. Include an Idempotency-Key header with a unique value for each request:

Idempotency-Key: a123b456c789d

If you retry a request with the same idempotency key, the API will return the result of the original request instead of processing the request again.