This article lists the errors that any Nearmap API can return, what causes them, and what to do about them. Each API also has its own errors, such as validation errors for its request fields.

How errors look

Most errors return JSON with a human-readable error message. Some also have a machine-readable code:

{ "error": "API key not found" }

A few errors come from Nearmap's gateway before the request reaches the API. These return plain text (Content-Type: text/plain), for example a missing API key:

HTTP/1.1 401 Unauthorized
Content-Type: text/plain; charset=utf-8

Unauthorized

In your client:

Check the HTTP status first.
Read the body as JSON only if Content-Type is application/json.
Handle errors by status and, where there is one, code. Avoid matching on the error text; it can change without notice. The messages in this article are listed to help you recognise an error while debugging.

Summary

Status	Meaning	Retry?
`400`	Something in the request is invalid. The causes depend on the API: check the API documentation for the specifics.	No. Fix the request first.
`401`	The API key is missing, invalid, or not allowed from where the request came from.	No. Fix the key or its restrictions.
`403`	Your subscription doesn't allow this request.	No.
`404`	Nothing was found. The causes depend on the API.	No. Change the request.
`429`	You sent too many requests for the API's rate limit, or your Daily API Rate Allowance is used up.	Yes, after `X-RateLimit-Reset` for a rate limit, or after `Retry-After` for the daily allowance.
`500`	Something went wrong on our side.	Yes. Wait a moment, and if it fails again, wait a bit longer before the next try, roughly doubling the wait each time.
`503`	The service is under heavy load and is protecting itself.	Yes. Wait a moment, and if it fails again, wait a bit longer before the next try, roughly doubling the wait each time.

401 Unauthorized

Message	Cause	What to do
`Unauthorized` (plain text)	No API key was sent.	Send `Authorization: Apikey <your API key>`.
`API key not found`	The API key doesn't exist, was revoked, or has expired.	In MyAccount, open Integrations → API Keys and check your key. To create a replacement, choose an application and select CREATE KEY, then update the key your client sends. You must be assigned to a subscription to create a key. See Create an API Key.
`Failed to validate IP or referer`	The API key has IP address or referrer restrictions and the request doesn't match them.	Send the request from an allowed IP address or site. To change restrictions as an administrator, open MyAccount → Integrations → API Apps, select the application, and choose Edit. Update its allowed IP addresses or referrer prefixes; referrer entries must include `https://` or `http://`. Changes can take up to one hour to take effect. See Manage API Applications.

403 Forbidden

Message	Cause	What to do
`Access forbidden`	Your subscription doesn't include the API you called.	Contact your account manager about access to the API.

Some APIs return other 403 errors, or use Access forbidden for more specific cases. See the API's error article for details.

429 Too Many Requests

Rate limits work the same way on every Nearmap API that has one, but the limits themselves differ per API and some APIs have none. Use the X-RateLimit-Limit response header to check your limit and X-RateLimit-Remaining to check how many requests you have left in the current time window. For limits by API, see API Rate Limits.

Message	Cause	What to do
`Rate limit exceeded` (plain text)	You sent more requests than the API's limit allows in its time window.	Wait until the time in the `X-RateLimit-Reset` header, then send the request again.

Responses from a rate-limited API carry these headers:

Header	Meaning
`X-RateLimit-Limit`	Your limit for the current time window.
`X-RateLimit-Remaining`	Requests left in the current time window.
`X-RateLimit-Reset`	When the limit resets, as a Unix timestamp in seconds.

For a Rate limit exceeded response, there's no Retry-After header: wait until the time in X-RateLimit-Reset. The daily allowance is separate; if the response includes Retry-After, use that header instead.

To calculate the delay from X-RateLimit-Reset:

Read the header as a Unix timestamp (seconds since January 1, 1970, at 00:00:00 UTC).
Get the current Unix timestamp in seconds. If your client reports time in milliseconds, divide it by 1,000.
Subtract the current timestamp from the reset timestamp. For example, a reset timestamp of 1700000060 minus a current timestamp of 1700000000 means you should wait 60 seconds. If the result is negative, the reset time has already passed.
Wait for that delay before retrying. Check the next response's status and headers; if it is another 429, calculate a new delay rather than retrying continuously.

Retries count toward the limit, so cap how often your client retries a failing request.

500 Internal Server Error

Message	Cause	What to do
`Internal Server Error`	Something went wrong on our side.	Retry a few times. Wait a bit longer before the next try, roughly doubling the wait each time. If the same request keeps failing, contact support with the request ID (see Contacting support).

503 Service Unavailable

Message	Cause	What to do
`Service rate limit exceeded`	The service is under heavy load and is protecting itself. This isn't your own rate limit: it can happen on any API, even when you're well within your limit.	Retry. Wait a bit longer before the next try, roughly doubling the wait each time.

Retrying

Don't retry 400, 401, 403, or 404. The same request will fail the same way.
Retry 500 and 503 a few times with exponential backoff (for example, after 1, 2, and 4 seconds), then stop.
After a 429, wait until the time in X-RateLimit-Reset, or in Retry-After if the response has one, before you retry.

Contacting support

Every response carries an X-Hyperweb-Requestid header. When you contact Nearmap support, include:

The request ID from X-Hyperweb-Requestid.
The time of the request, including the time zone.
The request URL, HTTP method, and request body, if applicable.
The HTTP status, response body, and response time.
The X-Amz-Cf-Id response header, if present.
Any proxy or service-mesh details relevant to the failure.

Remove API keys and other credentials before sharing request details. For the full checklist, see Capturing Information for Failed API Requests.