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

# Error Codes

> Bitrace AML API uses standard HTTP status codes along with custom error codes to provide detailed information about request issues.

## Response Format

All error responses follow this structure:

```json theme={null}
{
  "success": false,
  "code": 400,
  "msg": "Invalid request parameter",
  "data": null
}
```

## HTTP Status Codes

### 2xx Success

* **200 OK** - Request successful
* **201 Created** - Resource created successfully

### 4xx Client Errors

* **400 Bad Request** - Invalid request parameters
* **401 Unauthorized** - Missing or invalid API key
* **403 Forbidden** - API key doesn't have required permissions
* **404 Not Found** - Requested resource not found
* **405 Method Not Allowed** - Invalid method to access the resource
* **406 Not Acceptable** - Requested resource in invalid format
* **404 Not Found** - Requested resource not found
* **429 Too Many Requests** - Rate limit exceeded

### 5xx Server Errors

* **500 Internal Server Error** - Server error
* **502 Bad Gateway** - Upstream service error
* **503 Service Unavailable** - Service temporarily unavailable
* **504 Gateway Timeout** - Request timeout

## Common Error Codes

### Authentication Errors

#### 401 - Invalid API Key

```json theme={null}
{
  "success": false,
  "code": 401,
  "msg": "Invalid or missing API key",
  "data": null
}
```

**Solution**:

* Verify your API key is correct
* Check the `X-Access-Key` header is set
* Ensure your API key is active

#### 403 - Insufficient Permissions

```json theme={null}
{
  "success": false,
  "code": 403,
  "msg": "API key does not have permission for this endpoint",
  "data": null
}
```

**Solution**:

* Check your subscription plan includes this endpoint
* Contact support to upgrade your plan

### Parameter Errors

#### 400 - Invalid request params or payload

```json theme={null}
{
  "msg": "Your request is invalid.",
  "code": 400,
  "success": false,
  "status": "FAIL"
}
```

#### 400 - Invalid Address

```json theme={null}
{
  "msg": "Not supported network or wallet address",
  "code": 3000,
  "success": false,
  "status": "FAIL"
}
```

**Solution**:

* Verify the address format matches the network
* Check for typos in the address or network
* Use a supported network (see [KYA Supported Chains](/api-reference/endpoints/supported-chains/kya-supported-chains))

#### 400 - Missing Required Parameter

```json theme={null}

{
  "code": 400,
  "success": false,
  "error": "network is not empty",
  "status": "FAIL"
}
```

**Solution**:

* Include all required parameters
* Check API documentation for required fields

### Rate Limiting

#### 429 - Rate Limit Exceeded

```json theme={null}
{
	"code": 429,
	"msg": "Rate limit reached for requests.",
	"status": "ERROR",
	"success": false
}
```

**Solution**:

* Wait before retrying the request
* Implement exponential backoff
* Consider upgrading your plan for higher limits

### Transaction Errors

#### 400 - Invalid Transaction Hash

```json theme={null}
{
  "code": 3004,
  "msg": "Transaction hash not found or invalid",
  "status": "ERROR",
  "success": false
}
```

**Solution**:

* Verify the transaction hash is correct
* Check the transaction exists on the specified network
* Ensure the transaction has been confirmed

### Server Errors

#### 500 - Internal Server Error

```json theme={null}
{
  "success": false,
  "code": 500,
  "msg": "Internal server error. Please try again later",
  "data": null
}
```

**Solution**:

* Retry the request
* Check our status page for ongoing incidents
* Contact support if the error persists

#### 503 - Service Unavailable

```json theme={null}
{
  "success": false,
  "code": 503,
  "msg": "Service temporarily unavailable. Please retry later",
  "data": null
}
```

**Solution**:

* Wait before retrying
* Check our status page for maintenance updates
* Implement request queuing for critical operations

## Error Handling Best Practices

### JavaScript/TypeScript

```javascript theme={null}
try {
  const response = await axios.get(url, {
    headers: { 'X-Access-Key': apiKey }
  });

  if (!response.data.success) {
    throw new Error(response.data.msg);
  }

  return response.data.data;
} catch (error) {
  if (error.response) {
    // Server returned error response
    const { status, data } = error.response;

    switch (status) {
      case 401:
        console.error('Invalid API key');
        break;
      case 429:
        const retryAfter = data.data?.retryAfter || 60;
        console.log(`Retry after ${retryAfter} seconds`);
        break;
      default:
        console.error(`Error: ${data.msg}`);
    }
  } else {
    // Network error or request timeout
    console.error('Request failed:', error.message);
  }
}
```

### Python

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

def make_api_request(url, headers, params, max_retries=3):
    for attempt in range(max_retries):
        try:
            response = requests.get(url, headers=headers, params=params)

            if response.status_code == 429:
                retry_after = response.json().get('data', {}).get('retryAfter', 60)
                print(f"Rate limited. Retrying after {retry_after} seconds")
                time.sleep(retry_after)
                continue

            response.raise_for_status()
            data = response.json()

            if not data.get('success'):
                raise Exception(data.get('msg', 'API request failed'))

            return data.get('data')

        except requests.exceptions.RequestException as e:
            print(f"Attempt {attempt + 1} failed: {e}")
            if attempt < max_retries - 1:
                time.sleep(2 ** attempt)  # Exponential backoff
            else:
                raise

    return None
```

## Troubleshooting Checklist

* [ ] Verify API key is correct and active
* [ ] Check all required parameters are included
* [ ] Ensure parameter values are correctly formatted
* [ ] Verify network is supported
* [ ] Check address/hash format matches the network
* [ ] Review rate limits and usage
* [ ] Check service status page
* [ ] Retry with exponential backoff
* [ ] Contact support if issues persist

## Getting Help

If you encounter an error not documented here:

1. **Check the status page**: [status.bitrace.io](https://status.bitrace.io)
2. **Review our docs**: [API Reference](/api-reference)
3. **Search existing issues**: [GitHub Issues](https://github.com/bitrace-dev/APIs/issues)
4. **Contact support**: [support@bitrace.io](mailto:support@bitrace.io)

When reporting issues, please include:

* The error code and message
* The endpoint being called
* Request parameters (excluding sensitive data)
* Timestamp of the error
* Your API key's first 8 characters

## Related Resources

* [Authentication](/api-reference/authentication) - API key setup
* [API Reference](/api-reference) - Endpoint documentation
* [Quickstart](/api-reference/quickstart) - Getting started guide