Errors and retries

V2 API errors return JSON, including when the Accept header is omitted. Use the HTTP status to decide whether to correct your request or retry it.

Status	Meaning	Action
200	Request succeeded	Read the response body
401	Authentication failed	Check your Bearer token
403	API access or a token permission is missing	Check the project and token permissions
404	Project/location was not found or is outside your access	Check both public IDs and project membership
422	Request validation failed	Correct the named fields
429	Rate limit reached	Wait for `Retry-After`
500	Server error	Check the result before retrying a write

Validation errors

{
  "message": "The city field is required.",
  "errors": {
    "city": ["The city field is required."]
  }
}

The message summarizes the failure. The errors object identifies each invalid field; messages can differ depending on the request. A rejected V2 location update does not save a subset of its fields.

Empty hours and incomplete weeks

"hours": {} is valid and leaves hours unchanged. "hours": [] is invalid: hours must be a weekday object. A nonempty POST or PUT hours object must include all seven days. Use PATCH to update selected days instead:

{"hours":{"mon":"09:00-17:00"}}

Weekday values are strings or null, not objects such as {"open":"09:00","close":"17:00"}. See opening hours.

Rate limits and retries

The current shared API limit is 1,000 requests per minute. Read X-RateLimit-Limit and X-RateLimit-Remaining on responses; a 429 also includes Retry-After. Wait for that interval before retrying, and space subsequent requests out. Retrying a POST can create another location if the original request succeeded before the connection failed. Check whether the location already exists before retrying a create.

Addresses and coordinates

lat must be between -90 and 90; lng must be between -180 and 180. Zero is valid. The returned address field is address. POST and PUT can geocode synchronously when either coordinate is missing or zero. Both accept zero during validation but retain this older geocoding behavior. A PATCH affecting address or coordinate fields queues geocoding only if a coordinate is missing; it preserves supplied zero coordinates. The immediate response can still have null coordinates. For precise pins, supply both coordinates. Changing a phone or other unrelated field with PATCH does not trigger geocoding.

Start here

Account

Locations

Existing integrations

Validation errors

Empty hours and incomplete weeks

Rate limits and retries

Addresses and coordinates

​Validation errors

​Empty hours and incomplete weeks

​Rate limits and retries

​Addresses and coordinates

Validation errors

Empty hours and incomplete weeks

Rate limits and retries

Addresses and coordinates