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.
204 No Content	success	(empty)	Request was valid but no result exists (e.g. POI search inside a bounding box that contains nothing).
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.).