Skip to main content

API errors

The IPLocate API uses standard HTTP status codes and provides detailed error messages to help you handle issues programmatically.

HTTP status codes​

200
Success - Request processed successfully
400
Bad Request - Invalid input parameters
401
Unauthorized - Authentication or authorization error
404
Not Found - IP address not found
429
Too Many Requests - Rate limit exceeded
500
Internal Server Error - Server-side error

Error response format​

Error responses return a JSON object with a error property that describes what went wrong:

{
  "error": "Error message describing what went wrong"
}

Common errors​

400 Bad Request​

{
  "error": "Invalid IP address"
}

Common causes:

  • Malformed IPv4 or IPv6 address format
  • If behind a proxy, passing the result of an X-Forwarded-For header which may include multiple IP addresses, such as 127.0.0.1, 192.168.1.1
  • Passing an IP address that is undefined or null

401 Unauthorized​

{
  "error": "Missing API key"
}
{
  "error": "Invalid API key"
}

404 Not Found​

{
  "error": "Not found"
}

Common causes:

  • IP address or entity not found

429 Too Many Requests​

{
  "error": "Rate limit exceeded. Please upgrade your plan at iplocate.io/account"
}

Handling errors​

JavaScript example​

try {
  const response = await fetch('https://iplocate.io/api/lookup/8.8.8.8?apikey=YOUR_API_KEY');

  if (!response.ok) {
    const errorData = await response.json();
    console.error('API Error:', errorData.error);

    switch (response.status) {
      case 429:
        // Handle rate limiting
        const resetDate = new Date(response.headers.get('X-RateLimit-Reset') * 1000);
        console.log(`Rate limited. Try again after ${resetDate.toISOString()}`);
        break;
      case 401:
        // Handle authentication errors
        console.log('Check your API key.');
        break;
      default:
        console.log('Request failed:', response.status);
    }
    return;
  }

  const data = await response.json();
  console.log('Success:', data);

} catch (error) {
  console.error('Network error:', error);
}

Python example​

import requests

try:
    response = requests.get('https://iplocate.io/api/lookup/8.8.8.8', 
                          params={'apikey': 'YOUR_API_KEY'})

    if response.status_code != 200:
        error_data = response.json()
        print(f"API Error: {error_data['error']}")

        if response.status_code == 429:
            print(f"Rate limited. Resets at {response.headers['X-RateLimit-Reset']}")
        elif response.status_code == 401:
            print("Authentication failed. Check API key.")
        return

    data = response.json()
    print(f"Success: {data}")

except requests.RequestException as e:
    print(f"Network error: {e}")

Troubleshooting​

Getting 401 errors?​

  • Verify your API key is correct and active
  • Ensure you're not using an expired key
  • Ensure your API key is being passed in the request - see Authentication

Getting 429 errors?​

  • Check your current usage in the account dashboard
  • Upgrade your plan or purchase credits
  • Implement caching or request throttling in your application

Getting 500 errors?​

This indicates a server-side issue. Check our status page for any known issues, or contact us for support.