Skip to main content

​
Response Format

All error responses follow this structure: 
{
  "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

{
  "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

{
  "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

{
  "msg": "Your request is invalid.",
  "code": 400,
  "success": false,
  "status": "FAIL"
}

​
400 - Invalid Address

{
  "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)

​
400 - Missing Required Parameter


{
  "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

{
	"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

{
  "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

{
  "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

{
  "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

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

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
  2. Review our docs: API Reference
  3. Search existing issues: GitHub Issues
  4. Contact support: [email protected]
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