Errors & rate limits

Failures are explicit and typed: every error returns a structured envelope rather than a silent fallback.

Error envelope

Every error response shares one shape:

{
 "error": "VALIDATION_ERROR",
 "message": "window.to must be after window.from",
 "issues": [ … ], // present for VALIDATION_ERROR, the raw Zod issue array
 "detail": { /* endpoint-specific context, e.g. maxKm, openDriftEvents */ }
}

issues and detail are both optional and independent: issues is reserved for Zod validation failures; detail carries whatever free-form context a specific error needs (never both nested inside each other).

Status codes

Retries

Retry 429 and 503 with exponential backoff, or, on a 429, honour the Retry-After header (seconds) the API returns. Every response also carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (omitted on unlimited plans) so you can self-throttle before you hit the cap. 4xx other than 429 are deterministic: fix the request rather than retrying. The SDK throws GoableApiError (carrying status + code) for non-2xx and GoableNetworkError for transport failures.

Quotas and rate limits

On paid tiers the monthly quota is the billing line; overage is metered via Stripe once you exceed it. On Free (a hard cap) there is no overage: requests return 429 once the monthly quota is exhausted, resetting on the 1st of the month (UTC). The daily column is a per-tenant DDoS safety cap; it resets at 00:00 UTC and only kicks in for runaway loops.