Error Handling

All errors return a consistent JSON structure.

Error Format

All API responses use a unified envelope format. Error responses look like this:

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 20001,
  "error_message": "Missing API key"
}

Field	Description
success	Always false for errors
data	Always null for errors
error	Always true for errors
error_code	Numeric error code
error_message	Human-readable message

The X-Request-ID header contains the request ID for support requests.

HTTP Status Codes

Status	Meaning
400	Bad request
401	Missing or invalid API key
403	Key revoked
404	Endpoint not found
429	Rate limit exceeded
500	Server error
503	Service unavailable

Error Ranges

Range	Category
10xxx	Validation
20xxx	Authentication
30xxx	Rate/quota
40xxx	Internal

Code Examples

JavaScript

async function lookupIP(ip) {
  const response = await fetch(
    `https://api.hummingbirdapi.com/v1/geo/lookup?ip=${ip}`,
    { headers: { 'X-API-Key': process.env.HUMMINGBIRD_API_KEY } }
  );

  const result = await response.json();

  if (!result.success) {
    if (result.error_code === 30001) {
      // Rate limited — wait and retry
      await new Promise(r => setTimeout(r, 1000));
      return lookupIP(ip);
    }

    throw new Error(`API error ${result.error_code}: ${result.error_message}`);
  }

  return result.data;
}

Python

import requests
import time
import os

def lookup_ip(ip):
    response = requests.get(
        f'https://api.hummingbirdapi.com/v1/geo/lookup?ip={ip}',
        headers={'X-API-Key': os.environ['HUMMINGBIRD_API_KEY']}
    )
    result = response.json()

    if not result['success']:
        if result['error_code'] == 30001:
            # Rate limited — wait and retry
            time.sleep(1)
            return lookup_ip(ip)

        raise Exception(f"API error {result['error_code']}: {result['error_message']}")

    return result['data']

Best Practices

1. Check success — Don't assume requests succeed
2. Log X-Request-ID header — Include in logs for debugging
3. Retry transient errors — 429, 500, 503
4. Fail gracefully — Provide fallback behavior

Need Help?

1. Check the Error Codes reference
2. Include request_id when contacting support