Skip to main content

Response Format

All error responses follow this structure:

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

Solution:
  • Verify your API key is correct
  • Check the X-Access-Key header is set
  • Ensure your API key is active

403 - Insufficient Permissions

Solution:
  • Check your subscription plan includes this endpoint
  • Contact support to upgrade your plan

Parameter Errors

400 - Invalid request params or payload

400 - Invalid Address

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

Solution:
  • Include all required parameters
  • Check API documentation for required fields

Rate Limiting

429 - Rate Limit Exceeded

Solution:
  • Wait before retrying the request
  • Implement exponential backoff
  • Consider upgrading your plan for higher limits

Transaction Errors

400 - Invalid Transaction Hash

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

Solution:
  • Retry the request
  • Check our status page for ongoing incidents
  • Contact support if the error persists

503 - Service Unavailable

Solution:
  • Wait before retrying
  • Check our status page for maintenance updates
  • Implement request queuing for critical operations

Error Handling Best Practices

JavaScript/TypeScript

Python

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: 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