This article lists the errors that are specific to the Content API, what causes them and what to do about them. For errors that every Nearmap API can return, such as a missing or invalid API key, rate limits and server errors, see Nearmap API Error Codes. For how the Content API works, see the Content API handbook article.
Content API errors
Content API errors return JSON with a human-readable error message. Every 400, 403 and 500 also has a machine-readable code; 404s have only the message:
{ "code": "INVALID_COUNTRY", "error": "country is not supported" }
Handle errors by status and, where there is one, code. The messages in this article are listed to help you recognize an error while debugging and to tell apart errors that have no code.
Search errors
These apply to both endpoints: /search/address and /search/parcels.
400 Bad Request
Every 400 has a code. Don't retry a 400: fix the request first.
The request body
Code | Message | Cause | What to do |
|---|
REQUEST_PARSE_FAILURE
| failed to parse request parameters
| The body isn't valid JSON, or a field has the wrong type or is missing. | Check the body against the endpoint's API reference page. |
REQUEST_PARSE_FAILURE
| request could not be processed
| The body is valid, but a value in it was rejected while the search ran: usually an address that can't be looked up, or an AI content type or selector that isn't supported. | Check the address, and the ai entries in resources, against the API reference. |
INVALID_RESOURCE
| no resources provided
| The resources array is missing or empty. | Ask for at least one content type. |
INVALID_RESOURCE
| invalid resource
| A namespace or type isn't supported. | Use a value from the content type table in the Content API handbook article. |
INVALID_SELECTOR
| unsupported selector "<name>"
| A selector name is reserved for internal use. | Use only the selectors listed in the API reference. |
The location
Code | Message | Cause | What to do |
|---|
INVALID_ADDRESS
| address must not be blank
| In an address search, address.address contains only spaces. (An empty "" address returns REQUEST_PARSE_FAILURE.) | Send the street address. |
INVALID_COUNTRY
| country is not supported
| In an address search, country isn't US or AU. The value is case sensitive: au is rejected. | Send US or AU in capitals. |
INVALID_COUNTRY
| country is not supported
| A point, parcel or area search is in Canada or New Zealand, which the Content API doesn't cover. An aoi that crosses into either country is rejected as a whole, not clipped. | Search only in the United States or Australia. For an area near a border, draw it so it stays on the US side. |
INVALID_POINT
| aoi must be a point
| /search/point received a geometry other than a GeoJSON Point. (/search/parcels returns REQUEST_PARSE_FAILURE instead.)
| Send {"type": "Point", "coordinates": [longitude, latitude]}. |
INVALID_GEOMETRY
| request geometry is required to be a point, polygon or multipolygon
| /search/aoi received another GeoJSON type, such as a LineString, or an empty aoi. A malformed geometry (for example an unclosed polygon) returns REQUEST_PARSE_FAILURE instead.
| Send a Point, Polygon or MultiPolygon, with longitude first. |
INVALID_RADIUS
| radius must be great than 0 and at most 100
| /search/point received a radius that is missing, 0 or less, or more than 100. 100 itself is allowed. (A decimal such as 50.5 returns REQUEST_PARSE_FAILURE.)
| Send a whole number from 1 to 100. |
MULTIPLE_PARCELS_FOUND
| multiple parcels found
| The address, or the point sent to /search/parcels, matches more than one parcel. | Make the address more specific (unit or lot number), or move the point inside the parcel you want. |
Dates, paging and filters
Code | Message | Cause | What to do |
|---|
INVALID_DATE
| invalid date parameter format
| since or until isn't a YYYY-MM-DD date.
| Use YYYY-MM-DD, or a relative date such as 10D, 5M or 1Y. |
INVALID_DATE
| invalid relative date field
| A relative date has no valid number before its unit, for example xM. | Write a whole number followed by D (days), M (months) or Y (years). |
INVALID_DATE
| relative date parameter must have realistic time period
| A relative date is unrealistically large (over 1,000 years). | Use a shorter period. Content is only available from the last 2 years anyway. |
INVALID_DATE_RANGE
| since date cannot be after until date
| since is later than until.
| Swap or correct the two dates. |
INVALID_LIMIT
| limit must be a positive number
| limit is 0 or negative.
| Send a number from 1 to 300. |
INVALID_LIMIT
| limit must be between 1 and 300
| limit is above 300.
| Send a number from 1 to 300 and page with cursor. |
INVALID_OVERLAP
| overlap must be one of partial or full
| overlap has another value.
| Send partial or full, or leave it out. |
INVALID_CURSOR
| invalid cursor
| The cursor wasn't issued by this API or was changed. | Send the cursor exactly as you received it. |
403 Forbidden
Every 403 has a code. When your subscription is missing both the Content API and AI, you get API_NOT_ENTITLED first.
Code | Message | Cause | What to do |
|---|
API_NOT_ENTITLED
| Access forbidden
| Your API key’s subscription doesn’t include the Content API. | Contact your account manager about Content API access. |
AI_NOT_ENTITLED
| Access forbidden
| You asked for AI content ("namespace": "ai") and your subscription doesn’t include AI. The whole search fails, including any imagery you asked for. | Remove the ai entries and try again, or ask your account manager about AI access. |
AREA_NOT_AUTHORIZED
| User is not authorized to access this area or Area not authorized
| The location is outside the areas your subscription covers, or in a place Nearmap hasn’t captured, such as open sea. | Check the coordinates (longitude first) and that the location is in your subscription’s area. |
SUBSCRIPTION_NOT_SUPPORTED
| Unauthorized API Access
| Your subscription type doesn’t include the Content API. | The Content API needs a Property Intelligence or Location Intelligence subscription. Contact your account manager. |
ALLOWANCE_EXCEEDED
| Subscription allowance exceeded
| Property Intelligence: your subscription has used all its Property Credits. (Location Intelligence searches don’t use credits; see the download 429 below.) | Contact your account manager to add credits. |
404 Not Found
These don't have a code, so they are differentiated by their message.
Message | Cause | What to do |
|---|
Property not found
| No property matches the address or location. With a Location Intelligence subscription, this also covers an address that has no parcel. | Check the spelling of the address and that country is the country the address is in: the address is only looked up in that country. |
No coverage available
| Nearmap has no content of the requested types for this property in the requested dates. This includes an until date more than 2 years ago: content is only available from the last 2 years. | Ask for other content types, or move until to within the last 2 years. |
429 Too Many Requests
Message | Cause | What to do |
|---|
Rate limit exceeded (plain text)
| You sent more than 3,000 search requests in one hour. The hour starts with your first request. All your API keys share this limit, and requests to the old /property/resources/v1 URLs count toward it. | Wait until the time in the X-RateLimit-Reset header. There’s no Retry-After header. See API Error Codes. |
500 Internal Server Error
The Content API’s 500 has the code SYSTEM_ERROR. For what to do, see API Error Codes. Retrying doesn’t charge you twice.
Download errors
The download links in a search response (staticmap, tiles and aifeatures) point at other Nearmap APIs, but these errors are about the Content API's transaction tokens, which last 1 hour.
Status | Cause | What to do |
|---|
401
| The transaction token is expired, damaged, missing or sent in the URL instead of the Authorization header. | Run the search again for a new token and send it as Authorization: Transaction <token>. Then retry the download once. |
431 or 400, before the request reaches Nearmap
| The token (about 2,800 characters) didn't fit in a header size limit in your own setup. | Raise the maximum request header size of your proxy or HTTP library to at least 8 KB. |
429
| Location Intelligence only: your subscription’s Daily API Rate Allowance is used up for today. Each download counts against it. | Wait for the time in the Retry-After header, or contact your account manager about a larger allowance. |
Retrying Content API requests
The general retry rules are in API Error Codes. Two things are specific to the Content API:
- Retrying doesn't charge you twice. A search that failed and is retried doesn't use extra Property Credits.
- Allow at least 60 seconds before your client times out a search. Most searches return in well under a second, but some take much longer.
The Content API allows up to <RATE_LIMIT> requests per <RATE_WINDOW>, per user: all your API keys share one allowance, and requests to the old /property/resources/v1 URLs count toward it too. When you go over it, you get 429 Rate limit exceeded. For how rate-limit errors and headers work, see API Error Codes.