> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usebila.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Understanding Bila API error responses

## Error Response Format

Failed requests return `status: false` with a descriptive `message`:

```json theme={null}
{
  "status": false,
  "message": "Description of what went wrong"
}
```

## HTTP Status Codes

Bila uses standard HTTP status codes.

### Success Codes

| Code          | Description                   |
| ------------- | ----------------------------- |
| `200 OK`      | Request succeeded             |
| `201 Created` | Resource created successfully |

### Client Error Codes

| Code                       | Description                                   |
| -------------------------- | --------------------------------------------- |
| `400 Bad Request`          | Invalid request parameters                    |
| `401 Unauthorized`         | Missing or invalid API key                    |
| `403 Forbidden`            | Valid API key but insufficient permissions    |
| `404 Not Found`            | Requested resource doesn't exist              |
| `409 Conflict`             | Resource already exists (duplicate reference) |
| `422 Unprocessable Entity` | Request body failed validation                |
| `429 Too Many Requests`    | Rate limit exceeded                           |

### Server Error Codes

| Code                        | Description                     |
| --------------------------- | ------------------------------- |
| `500 Internal Server Error` | Something went wrong on our end |
| `502 Bad Gateway`           | Upstream service unavailable    |
| `503 Service Unavailable`   | API is temporarily unavailable  |

## Common Error Messages

### Authentication Errors

```json theme={null}
{
  "status": false,
  "message": "Unauthorized - Invalid or missing API key"
}
```

### Validation Errors

```json theme={null}
{
  "status": false,
  "message": "Invalid phone number format"
}
```

### Resource Not Found

```json theme={null}
{
  "status": false,
  "message": "Account not found"
}
```

### Duplicate Reference

```json theme={null}
{
  "status": false,
  "message": "A transaction with this reference already exists"
}
```

### Insufficient Balance

```json theme={null}
{
  "status": false,
  "message": "Insufficient balance in source account"
}
```

## Handling Errors

<CodeGroup>
  ```javascript Node.js theme={null}
  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);
  }
  ```

  ```python Python theme={null}
  import requests

  try:
      response = requests.post(
          'https://api.usebila.com/api/v1/bila/transfers/bank-account',
          headers={
              'x-api-key': 'sk_live_your_api_key_here',
              'Content-Type': 'application/json'
          },
          json={
              'amount': 1000,
              'reference': 'transfer-001',
              # ... other fields
          }
      )
      
      data = response.json()
      
      if not data['status']:
          # Handle API error
          print(f"API Error: {data['message']}")
      else:
          # Success
          print(f"Transfer initiated: {data['data']}")

  except requests.exceptions.RequestException as e:
      # Handle network/unexpected errors
      print(f"Request failed: {e}")
  ```
</CodeGroup>

## Best Practices

<AccordionGroup>
  <Accordion title="Always check the status field">
    Don't rely solely on HTTP status codes. Always check the `status` field in the response body.
  </Accordion>

  <Accordion title="Log error messages">
    Log the error `message` for debugging purposes.
  </Accordion>

  <Accordion title="Implement retry logic">
    For `5xx` errors and rate limiting, implement exponential backoff retry logic.
  </Accordion>

  <Accordion title="Handle edge cases">
    Account for scenarios like network timeouts, invalid JSON responses, and service unavailability.
  </Accordion>
</AccordionGroup>