Skip to main content

​
Error Response Format

When an API request fails, the response will include a status of false and a descriptive message: 
{
  "status": false,
  "message": "Description of what went wrong"
}

​
HTTP Status Codes

The Bila API uses standard HTTP status codes to indicate the success or failure of requests.

​
Success Codes

CodeDescription
200 OKRequest succeeded
201 CreatedResource created successfully

​
Client Error Codes

CodeDescription
400 Bad RequestInvalid request parameters
401 UnauthorizedMissing or invalid API key
403 ForbiddenValid API key but insufficient permissions
404 Not FoundRequested resource doesn’t exist
409 ConflictResource already exists (duplicate reference)
422 Unprocessable EntityRequest body failed validation
429 Too Many RequestsRate limit exceeded

​
Server Error Codes

CodeDescription
500 Internal Server ErrorSomething went wrong on our end
502 Bad GatewayUpstream service unavailable
503 Service UnavailableAPI is temporarily unavailable

​
Common Error Messages

​
Authentication Errors

{
  "status": false,
  "message": "Unauthorized - Invalid or missing API key"
}

​
Validation Errors

{
  "status": false,
  "message": "Invalid phone number format"
}

​
Resource Not Found

{
  "status": false,
  "message": "Account not found"
}

​
Duplicate Reference

{
  "status": false,
  "message": "A transaction with this reference already exists"
}

​
Insufficient Balance

{
  "status": false,
  "message": "Insufficient balance in source account"
}

​
Handling Errors

try {
  const response = await fetch('https://api.usebila.com/api/v1/bila/transfers/bank-account', {
    method: 'POST',
    headers: {
      'x-api-key': 'sk_live_your_api_key_here',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      amount: 1000,
      reference: 'transfer-001',
      // ... other fields
    })
  });

  const data = await response.json();

  if (!data.status) {
    // Handle API error
    console.error('API Error:', data.message);
    return;
  }

  // Success
  console.log('Transfer initiated:', data.data);

} catch (error) {
  // Handle network/unexpected errors
  console.error('Request failed:', error);
}

​
Best Practices

Don’t rely solely on HTTP status codes. Always check the status field in the response body.
Log the error message for debugging purposes.
For 5xx errors and rate limiting, implement exponential backoff retry logic.
Account for scenarios like network timeouts, invalid JSON responses, and service unavailability.