Errors

Every error outside the token endpoint uses the same JSON shape and an HTTP status that matches it.

{
  "error": {
    "code": "validation_error",
    "message": "The window between from and to cannot exceed 31 days.",
    "request_id": "req_01J8ZQ4K6M2V7T9B",
    "details": [{ "field": "to", "issue": "must be at most 31 days after from" }]
  }
}

• Branch on code, not on message. Messages are for humans and can change.
• request_id is also returned in the X-Request-Id header of every response. Include it when you contact support.
• details is only present on validation_error.

The token endpoint uses the OAuth format instead; see Authentication.

Codes

Status	code	Meaning	Retry?
400	validation_error	A parameter is missing or invalid.	No, fix the request.
401	unauthorized	Token missing, malformed or expired.	Once, after getting a new token.
403	forbidden	Token lacks the scope, or asks for a location it cannot see.	No.
404	not_found	The resource does not exist or is not visible to you.	No.
429	rate_limited	Too many requests.	Yes, after Retry-After.
500	internal	Something failed on our side.	Yes, with backoff.

Retrying safely

All v1 endpoints are read-only, so every request is safe to repeat. For 429 and 500:

• Wait for Retry-After seconds when the header is present.
• Otherwise use exponential backoff with jitter: 1 s, 2 s, 4 s, 8 s, up to 5 attempts.
• If a 401 persists after refreshing the token, your credentials were probably rotated or revoked. Stop and alert a human.