Searching… for

No results found.

Try a different search term or check your spelling.

Showing all results.

Meet API v2.0 with UK support 🇬🇧 Try it out

Guides
for everything Geocodio

Guides
403 Forbidden

403 Forbidden

How to troubleshoot when you get a 403 Forbidden error from the Geocodio API

Quick Answer

A 403 means Geocodio recognized the request but refused it. There are three common causes: you've reached a usage limit, your API key doesn't have permission for that endpoint, or the key itself isn't valid. The error message in the response body will tell you which.

Unlike a 429, a 403 will not resolve by retrying. Fix the underlying cause first.

Check whether you've reached a usage limit

If the response says something like You can't make this request as it is above your daily maximum, you've hit either the daily usage limit set on your account or the free tier ceiling with no payment method on file.

  • Pay-as-you-go accounts include 2,500 free lookups per day. Beyond that, a payment method is required.

  • If you've set a daily usage limit, requests are refused once you reach it. The counter resets at midnight EST.

  • You can review or change your limit in the dashboard. See Set a usage limit.

Remember that data appends count toward your usage. Geocoding 2,000 addresses with one append is 4,000 lookups, not 2,000.

Check that your API key has permission for that endpoint

By default, an API key can only reach the single and batch geocoding endpoints. The Lists API and the Distance API endpoints have to be enabled per key.

If the response mentions permissions, open your API keys in the dashboard and enable the endpoints that key needs.

This is the most common cause of a 403 when the same key works fine for ordinary geocoding but fails on /lists or /distance.

Check that the API key is valid

  • Confirm the key matches one listed in your dashboard, with no extra whitespace or truncation

  • Confirm the key hasn't been revoked

  • Confirm you're using the right account. Enterprise keys work against api.enterprise.geocod.io and self-serve keys against api.geocod.io. A key from one will not work on the other

  • If your account has IP address limiting configured for the key, confirm the request is coming from an allowed address

Handling 403 in your integration

A 403 is a signal to stop, not to retry. Retrying will not succeed and, where the cause is a usage limit, it can obscure the real problem in your logs.

Log the error message from the response body — it distinguishes between the causes above — and surface it rather than treating it as a generic failure.

Still stuck?

Contact our support team with the time of the request and the API key's name (never the key itself), and we'll take a look.