Responses, errors, and limits

JSON responses

Successful responses use success and data. Metadata includes a request ID and, for paginated collections, pagination fields. This empty-list example is illustrative:

{
  "success": true,
  "data": [],
  "meta": {
    "request_id": "example-request-id",
    "page": 1,
    "per_page": 50,
    "total": 0,
    "pages": 0
  }
}

204 No Content responses have no JSON body. CSV downloads use text/csv.

Pagination and search

Objects and managed-resource collections accept page (starting at 1), per_page (default 50, maximum 500), and search (2–100 characters after trimming). Continue while the current page is below meta.pages. History defaults to 500 points per page. Command, RFID, login-history, and object-event lists use a capped per_page limit rather than page navigation; see each endpoint. Search matches registered fields within the account’s access scope. % and _ are literal characters. Managed-resource lists support registered exact field filters and sort / order. Object lists sort by name, with match ranking when search is supplied; their name, plate, and SIM filters are partial matches.

Limits

Limit	Value
Authenticated requests	60 per API token per 60-second window
Collection page size	Up to 500
Object batch size	Up to 100
History or date-based report interval	Up to 93 days
Route and mileage points	Default 5,000; maximum 10,000
Stop and drive calculation points	Up to 10,000
Generated report rows	Up to 10,000

Successful authenticated requests expose X-RateLimit-Limit and X-RateLimit-Remaining. On 429, back off before retrying. Avoid immediate retry loops and spread polling over time.

Errors

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "A valid API token is required."
  },
  "meta": { "request_id": "example-request-id" }
}

HTTP status	Typical code	What to do
401	`UNAUTHORIZED`	Check the token, account status, and API enablement.
403	`ACCOUNT_EXPIRED`, `PERMISSION_DENIED`, `READ_ONLY_ACCOUNT`, `TOKEN_PERMISSION_DENIED`	Check account access and required permissions. `TOKEN_PERMISSION_DENIED` means the token is valid but lacks the permission required by the requested method and route: edit the token’s permissions or use another appropriately scoped token.
404	`OBJECT_NOT_FOUND`, `RESOURCE_NOT_FOUND`, `HISTORY_NOT_FOUND`	Check the identifier and your access.
409	`OBJECT_EXISTS`, `OBJECT_LIMIT_REACHED`	Resolve the conflict before retrying.
422	`DATE_RANGE_REQUIRED`, `INVALID_DATE_RANGE`, `DATE_RANGE_TOO_LARGE`	Correct the request parameters.
429	`RATE_LIMIT_EXCEEDED`	Back off and reduce request frequency.
503	`WRITES_DISABLED`	Writes are temporarily unavailable; contact Graviton support.
503	`RATE_LIMIT_UNAVAILABLE`	Retry later and share the request ID if it persists.

Log the HTTP status, error.code, and meta.request_id. Avoid automatically retrying command or write requests after an ambiguous timeout: first check whether the original operation completed.

Get started

Integrate

Responses, errors, and limits

JSON responses

Limits

Errors

​JSON responses

​Pagination and search

​Limits

​Errors

JSON responses

Pagination and search

Limits

Errors