IP Intelligence API Error Codes & Troubleshooting Guide
Common HTTP status codes and error responses returned by the IP Intelligence API with reasons and fixes.
Try IP Intelligence Demo →Authentication Errors
401 - AUTH_ERROR
Authentication failed
Reason: Invalid API key, signature mismatch, expired timestamp, or nonce reuse
Fix: Regenerate signature with correct payload and ensure fresh timestamp + unique nonce
Authentication failed
Reason: Invalid API key, signature mismatch, expired timestamp, or nonce reuse
Fix: Regenerate signature with correct payload and ensure fresh timestamp + unique nonce
Validation Errors
400 - INVALID_INPUT
Invalid request body
Cases:
• Missing required fields (projectId, apiKey, nonce, timestamp)
• Missing ip (single) or ips (batch)
• Invalid IP format
• More than 50 IPs in batch
Fix: Validate IP format and ensure correct payload
Invalid request body
Cases:
• Missing required fields (projectId, apiKey, nonce, timestamp)
• Missing ip (single) or ips (batch)
• Invalid IP format
• More than 50 IPs in batch
Fix: Validate IP format and ensure correct payload
Access Errors
403 - FORBIDDEN
Request blocked
Reason: Invalid origin, missing Cloudflare headers, or failed Turnstile verification (demo)
Fix: Ensure request is sent from allowed origin or valid backend with proper headers
Request blocked
Reason: Invalid origin, missing Cloudflare headers, or failed Turnstile verification (demo)
Fix: Ensure request is sent from allowed origin or valid backend with proper headers
Rate Limiting
429 - RATE_LIMIT_EXCEEDED
Too many requests
Reason: Requests per minute exceeded
Fix: Retry later or upgrade plan
Too many requests
Reason: Requests per minute exceeded
Fix: Retry later or upgrade plan
Server Errors
503 - SERVICE_UNAVAILABLE
Service under maintenance
Fix: Retry after some time
Service under maintenance
Fix: Retry after some time
500 - SERVER_ERROR
Unexpected failure during processing
Fix: Retry or contact support if persistent
Unexpected failure during processing
Fix: Retry or contact support if persistent
Ensure valid IP format, correct signature generation, and respect rate limits to avoid most errors.
Next Steps
Fix issues and continue using the IP Intelligence API: