Errors

The Yatmo API uses standard HTTP status codes. The response body is usually a short plain-text explanation — not a JSON envelope.

Error shape

Most failures return a short string in the response body, not a structured JSON object:

HTTP/1.1 400 Bad Request
Content-Type: text/plain

Geolocation outside BE

Log both the status code and the body. The body is intended to be human-readable; don’t pattern-match it programmatically except as a last resort.

Name	In	Type	Description
200 OK	success	JSON	Normal response with the requested payload.
200 with no result	success	JSON	A valid request that finds nothing still answers `200`: `/points` returns `[]` for an area with no place or outside the market, and a nearest-place lookup returns `null`. It is a result, not an error. The API does not use `204`.
400 Bad Request	client	text	Malformed parameters: invalid lat/lng, out-of-range zoom, unparseable bounding box. Fix the request and don’t retry.
401 Unauthorized	client	text	Missing or unknown license key. Check the header is set (see /api/auth).
403 Forbidden	client	text	Key is valid but the request violates a restriction: wrong domain/origin, IP not on allow-list, country not authorized.
404 Not Found	client	text	Endpoint doesn’t exist, or the resource queried (e.g. a specific POI id) wasn’t found.
429 Too Many Requests	client	text	You’re sending too many calls. Slow down. If it persists, email info@yatmo.com.
500 Internal Server Error	server	text	Bug on our side. Safe to retry after a short backoff.
503 Service Unavailable	server	text	Temporary — usually a downstream cache warmup. Retry after a few seconds.

Cache 200s, surface 4xx, retry 5xx — the standard rule covers 95% of cases.
4xx is your problem; 5xx is ours. 401 / 403 / 404 indicate a fix on your side; 500 / 503 suggest waiting and trying again.
Bound retries. Exponential backoff with a max of 3 tries on 5xx; on 429, slow down and don’t hammer.
Log the body. The status alone is rarely enough — the body usually tells you exactly what went wrong (“Geolocation outside BE”, “Bound1 and Bound2 must be filled”, etc.).