> ## Documentation Index
> Fetch the complete documentation index at: https://api-doc.track.graviton.ma/llms.txt
> Use this file to discover all available pages before exploring further.

# Responses, errors, and limits

> Handle JSON envelopes, pagination, throttling, and failures.

## 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:

```json theme={null}
{
  "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

```json theme={null}
{
  "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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.