Error Handling

How Errors Work

When something goes wrong, the API tells you about it with a standard HTTP status code and a JSON body. No cryptic codes, no empty responses, no mysterious silence. You get a status code and a human readable message.

Status Codes

Here’s what you might see:

200 OK

Everything worked. You got your data. This is the one you want.

400 Bad Request

You sent something the API couldn’t understand. Usually this means the IP address you provided isn’t actually a valid IP address. Things like 999.999.999.999 or not-an-ip or your cat walking across the keyboard.

{
  "error": "Invalid IP address format",
  "status": 400
}

How to fix it: Check that you’re sending a valid IPv4 or IPv6 address. Validate on your end before making the request. Your future self will thank you.

404 Not Found

The endpoint you requested doesn’t exist. Double check the URL. Maybe there’s a typo. Maybe you’re hitting /api/ip/ instead of /api/{ip}. It happens.

{
  "error": "Not found",
  "status": 404
}

How to fix it: Check the endpoint documentation and make sure your URL matches.

429 Too Many Requests

You’re sending too many requests too fast. The API is asking you, politely but firmly, to slow down. See the rate limits page for details on what “too many” means and how to back off properly.

{
  "error": "Too many requests. Please slow down.",
  "status": 429
}

How to fix it: Wait a minute, then reduce your request rate. Add exponential backoff to your retry logic.

500 Internal Server Error

Something broke on our end. This is not your fault. We try very hard to never return 500s, but sometimes upstream data providers have a bad day. Sometimes servers get grumpy. Sometimes Mercury is in retrograde and computers just stop cooperating.

{
  "error": "Internal server error",
  "status": 500
}

How to fix it: You can’t, really. Wait a bit and try again. If it keeps happening, something is probably on fire and we’re already working on it.

Handling Errors Like a Professional

Here’s the general approach:

Always check the status code. Don’t just assume every response is a 200. Parse the status code first, then decide what to do with the body.

Don’t retry 400s. If the API says your request is bad, sending the same bad request again won’t make it less bad. Fix the request first.

Do retry 500s. But not immediately, and not forever. Wait a few seconds, try again. If it fails three times in a row, give up and log it so you can investigate later.

Handle 429s with backoff. Wait, then retry with increasing delays. Don’t just sleep for one second and hammer the endpoint again.

Log errors. When things go wrong, you want to know about it. Log the status code, the error message, and the request that caused it. Future you, debugging at 2 AM, will appreciate the breadcrumbs.

A Quick Example

Here’s a simple error handling pattern in JavaScript:

const response = await fetch("https://whatismyip.technology/api/8.8.8.8");

if (response.ok) {
  const data = await response.json();
  // do something useful with data
} else if (response.status === 429) {
  // slow down, wait, retry
} else if (response.status >= 500) {
  // not our fault, retry after a delay
} else {
  const error = await response.json();
  console.error(`API error ${response.status}: ${error.error}`);
}

Nothing fancy. Check the status, act accordingly, move on with your life.