Error Codes and Descriptions

An unsuccessful request to a Nearmap service will return an HTTP status code indicating an error. The status code for authentication failure is 401 Unauthorized. All API Key related failures will return a 401 status code.

In addition to the status code of 401, a small JSON payload is returned describing the error. The possible JSON error descriptions are:

{"error":"Failed to validate IP or referrer"} — The failure is related to the IP range or HTTP referrer restrictions that were set on the API Application associated with the API Key. Check whether the request came from a valid IP address and referrer. A useful diagnostic step is to remove the restrictions from the API Application, or use a different API Application that does not have the restrictions (and different API Key for that API Application), and see if the error still occurs.

{"error":"API key not found"} — All other API Key related errors will return this message.

The means of finding out the HTTP status code and the JSON payload will depend on the application that you are trying to integrate with Nearmap.

Capitalization

If you are using an HTTP Authorization header, the Authorization type must be "Apikey" – note the capital A. If on the other hand you are using the "apikey" parameter in the URL, capitalization is not significant. For example, all of the following are valid in a URL: "apikey=", "APIKEY=", "ApIkEy=".

Is everything enabled?

Check that the API Application associated with the API Key is enabled.

Check that the user who owns the API Key is enabled and subscribed. See Managing your Nearmap subscriptions and user logins for details.

Any one of the things listed here could explain why an API key isn't working:

• API app could have been deleted
• Security settings changed
• User access disabled
• User account disabled
• Entire account not valid
• Changed the subscription
• API Key was deleted by the Administrator
• IP Restrictions were placed on the API and the user is accessing them from a non-valid IP address
• Customer has exceeded monthly usage and has been restricted
• Customer has been restricted due to non-payment
• They are no longer a customer with Nearmap

Timeout Period

Changes related to an existing API Key can take up to an hour to take effect. For example:

• If you disable an API Application, the API Key may continue to provide access for up to an hour.
• Changes to the access restrictions on an API Application may take up to an hour to take effect.