Skip to main content

Troubleshooting

Common issues and how to resolve them.

Invalid Coordinates (400)​

Symptom: You receive a 400 Bad Request response.

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

Common causes:

  • Latitude and longitude are swapped. Latitude is -90 to 90, longitude is -180 to 180.
  • Coordinates are passed as strings with extra whitespace or non-numeric characters.
  • Using comma-separated values in the wrong format. The path format is {latitude},{longitude} with no spaces.

Fix: Verify that latitude comes first, is between -90 and 90, and longitude is between -180 and 180. Ensure no spaces around the comma in path parameters.

Authentication Failures (401)​

Symptom: You receive a 401 Unauthorized response.

Common causes:

  • Missing the X-API-Key header entirely.
  • Using an incorrect header name (e.g., Authorization instead of X-API-Key).
  • API key has been revoked from the dashboard.
  • Extra whitespace or newline characters in the key value (common when copying from environment variables).

Fix: Confirm the header is exactly X-API-Key and the value matches a valid, non-revoked key from your dashboard. Test with cURL to isolate whether the issue is in your HTTP client:

curl -v "https://api.boxesnlines.com/geo/country/fromGps/40.7128,-74.0060" \
  -H "X-API-Key: YOUR_API_KEY"

The -v flag shows request headers so you can verify the key is being sent correctly.

Rate Limiting (429)​

Symptom: You receive a 429 Too Many Requests response.

{
  "type": "https://tools.ietf.org/html/rfc6585#section-4",
  "title": "Too Many Requests",
  "status": 429,
  "detail": "Rate limit exceeded. Please try again later."
}

Common causes:

  • Exceeding the burst rate: anonymous/unauthenticated requests are limited to 10/min; authenticated users get 1,000/min regardless of plan.
  • Exceeding your monthly request quota.
  • Not implementing caching for repeated lookups of the same coordinates.

Fix:

  1. Check the X-RateLimit-Remaining response header to monitor your remaining quota. See Rate Limits for all available headers.
  2. Implement exponential backoff: wait 1s, then 2s, then 4s, etc.
  3. Cache results -the same coordinates always return the same country/subdivision.
  4. If you consistently hit limits, upgrade your plan.

No Data at Coordinates (404)​

Symptom: You receive a 404 Not Found response for valid coordinates.

This is expected behavior, not an error. A 404 means the coordinates do not fall within any recognized country or subdivision boundary. Common locations that return 404:

  • Oceans and seas (e.g., 0.0, 0.0 is in the Gulf of Guinea)
  • Antarctica (e.g., -85.0, 0.0)
  • Disputed territories that are not assigned to any country in the dataset

Fix: Handle 404 as a valid "no result" case in your application logic, not as an error:

if (response.status === 404) {
  // Coordinates are not within any known boundary
  // This is expected for ocean, Antarctica, etc.
  return null;
}

Common Integration Mistakes​

Swapping Latitude and Longitude​

The API expects latitude,longitude order (matching standard geographic convention). If you get unexpected results, check that you have not reversed them. A quick test: latitude for most populated areas is between -60 and 70, while longitude spans -180 to 180.

Using the Wrong Country Code Format​

The Point-in-Area country check requires ISO 3166-1 alpha-3 codes (e.g., USA for United States, BRA for Brazil). Subdivision checks use ISO 3166-2 codes (e.g., US-NY).

Not Handling Plain-Text Responses​

The country and subdivision lookup endpoints return plain strings (e.g., "USA", "US-NY"), not JSON objects. Use response.text() in JavaScript or response.text in Python:

// Correct
const country = await response.text(); // "USA"

// Incorrect -will include quotes
const country = await response.json(); // USA (without quotes, but type is string)

Forgetting to URL-Encode Subdivision Codes​

Subdivision codes like US-NY contain a hyphen, which is safe in URL paths. However, if you are passing them via query parameters in other contexts, ensure proper URL encoding.

Still Need Help?​