Error Codes

All API errors with resolution steps.

Error Format

All API responses use a unified envelope format:

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

Error Ranges

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

---

Validation (10xxx)

10001 — Invalid IP Address

HTTP 400

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 10001,
  "error_message": "Invalid IP address format"
}

Fix: Use valid IPv4 (192.0.2.1) or IPv6 (2001:db8::1).

---

10002 — Private IP Address

HTTP 400

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 10002,
  "error_message": "Cannot geolocate private IP address"
}

Fix: Use a public IP. Private ranges: 10.0.0.0/8, 172.16.0.0/12, 192.168.0.0/16.

---

Authentication (20xxx)

20001 — Missing API Key

HTTP 401

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

Fix: Add the X-API-Key header:

curl -H "X-API-Key: hb_live_xxxxx" ...

---

20002 — Invalid API Key

HTTP 401

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 20002,
  "error_message": "Invalid API key"
}

Fix:

1. Verify key starts with hb_live_
2. Check key exists in dashboard
3. Remove extra whitespace

---

20003 — API Key Revoked

HTTP 403

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 20003,
  "error_message": "API key has been revoked"
}

Fix: Create a new key in your dashboard.

---

Rate/Quota (30xxx)

30001 — Rate Limit Exceeded

HTTP 429

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 30001,
  "error_message": "Rate limit exceeded"
}

Fix:

1. Check Retry-After header for wait time
2. Implement exponential backoff
3. Upgrade for higher limits

---

30002 — Quota Exceeded

HTTP 429

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 30002,
  "error_message": "Quota exceeded"
}

Fix:

1. Wait for reset
2. Upgrade your plan

---

Internal (40xxx)

40001 — Internal Server Error

HTTP 500

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 40001,
  "error_message": "Internal server error"
}

Fix: Retry after a short delay. If persistent, contact support with the X-Request-ID header value.

---

40002 — Service Unavailable

HTTP 503

{
  "success": false,
  "data": null,
  "error": true,
  "error_code": 40002,
  "error_message": "Service temporarily unavailable"
}

Fix: Retry with exponential backoff. Check status.hummingbirdapi.com.

---

Quick Reference

Code	HTTP	Message
10001	400	Invalid IP address format
10002	400	Cannot geolocate private IP
20001	401	Missing API key
20002	401	Invalid API key
20003	403	API key revoked
30001	429	Rate limit exceeded
30002	429	Quota exceeded
40001	500	Internal server error
40002	503	Service unavailable

Need Help?

Include the X-Request-ID header value when contacting [email protected].