Skip to main content

Error Handling

The API uses standard HTTP status codes and returns errors in the Problem Details format.

HTTP Status Codes​

StatusDescription
200Success
400Invalid request (bad coordinates, missing parameters)
401Missing or invalid API key
404Resource not found (no country/subdivision at coordinates)
429Rate limit exceeded

Error Response Format​

Error responses follow the RFC 9457 Problem Details format:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Latitude must be between -90 and 90"
}

Handling Rate Limits (429)​

When you exceed your plan's rate limit, the API returns a 429 status code.

Best Practices
  • Implement exponential backoff when receiving 429 responses
  • Cache responses when possible to reduce request volume
  • Monitor your usage in the dashboard
  • Consider upgrading your plan if you consistently hit limits

Handling 404 Responses​

A 404 response means the coordinates don't fall within any known region. Common causes:

  • Coordinates are in the ocean
  • Coordinates are in Antarctica or other unclaimed territory
  • Coordinates are in a disputed territory
info

A 404 for coordinates is a valid response, not an error. It means the point does not fall within any recognized boundary. Handle it gracefully in your application.

Example Error Handling​

const response = await fetch(
  "https://api.boxesnlines.com/geo/country/fromGps/40.7128,-74.0060",
  { headers: { "X-API-Key": "YOUR_API_KEY" } }
);

switch (response.status) {
  case 200:
    const country = await response.text();
    console.log(`Country: ${country}`);
    break;
  case 401:
    console.error("Invalid API key");
    break;
  case 404:
    console.log("No country found at these coordinates");
    break;
  case 429:
    console.warn("Rate limit exceeded, retrying...");
    // Implement exponential backoff
    break;
  default:
    console.error(`Unexpected error: ${response.status}`);
}