Errors & limits

Response shape

Every v2 response has the same envelope:

{
  "data": { },
  "meta": { "pagination": { "limit": 50, "offset": 0, "count": 12 } }
}

meta.pagination only appears on list endpoints.

Errors

v2 errors carry a stable code you can write code against — switch on error.code, never on error.message, which can change:

{ "error": { "code": "DEVICE_NOT_FOUND", "message": "Dispositivo non trovato." } }

HTTP	error.code	Meaning
400	IMEI_REQUIRED	Missing IMEI in the path
400	BAD_REQUEST	Invalid parameters (e.g. history range too wide, from/to not ISO-8601)
400	COORDINATES_REQUIRED	Missing lat/lng on /devices/nearest
400	INVALID_COORDINATES	lat/lng out of range or not numeric
403	API_KEY_REQUIRED	Authenticated but not with an API key (e.g. a web session), or key missing
403	(free text)	Missing permission/scope on the key — {"error": "API key senza permesso: <permission>"}
403	FORBIDDEN	A specific permission is missing (e.g. commands not enabled for a sub-account)
404	DEVICE_NOT_FOUND	Device doesn’t exist or is outside the key’s scope — the two cases aren’t distinguished, so as not to reveal the existence of an IMEI that isn’t yours
404	LOCATION_NOT_FOUND	The device hasn’t sent a position yet
429	(no dedicated code)	Rate limit exceeded
500	INTERNAL_ERROR	Our error

Authentication errors outside the v2 envelope

Requests rejected before entering the v2 router (unknown, revoked, or IP-blocked API key) use the general authentication codes — API_KEY_INVALID, API_KEY_REVOKED, API_KEY_OWNER_INACTIVE, API_KEY_IP_BLOCKED — with the same {"message", "code"} shape. They aren’t listed above because they don’t belong to v2’s {"error": {...}} envelope, but they’re still 403.

Rate limiting

Limit	Value
Per key, per minute	120
Per key, per hour	1000
Per IP address, per minute	120

Over the limit: 429. Responses carry no X-RateLimit-* or Retry-After header: size your client around the numbers above, not around a header that doesn’t exist.

Pagination

Parameter	Default	Range
limit	varies per endpoint (50 or 500 depending on the resource)	see the resource’s page
offset	0	≥ 0

Out-of-range values are clamped, not rejected: limit=99999 becomes the maximum allowed for that endpoint, not an error. meta.pagination.count is the number of items on the current page, not the resource’s total count.