> ## Documentation Index
> Fetch the complete documentation index at: https://developers.vizito.eu/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> What each status means, and what to do about it.

Errors are returned as an HTTP status with a short JSON body, usually `{ "message": "..." }` or `{ "error": "..." }`. Some endpoints answer with a bare status and no body at all, so **read the status first** and treat the body as a hint.

| Status | Meaning                                                               | What to do                                                                                       |
| ------ | --------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `200`  | Success                                                               | —                                                                                                |
| `400`  | The request was understood but could not be carried out               | Read the message: a malformed id, a missing required parameter, or an object that does not exist |
| `401`  | The location could not be resolved for your credential                | Check the `company_id`, and that your key covers it                                              |
| `403`  | The credential was refused, or the endpoint is off limits to API keys | See [Authentication](/api-reference/authentication)                                              |
| `404`  | No such route, or no such object                                      | Check the path and the id                                                                        |
| `429`  | Too many refused credentials from this IP                             | Wait out the 15-minute window; fix the key first                                                 |
| `500`  | Something went wrong on our side                                      | Retry; if it persists, [contact support](mailto:support@vizito.eu)                               |

<Note>
  Failing to resolve a location is reported as `400`, `401` or `404` depending on the endpoint. Treat all three the same way: the location id is wrong, or your key does not cover it.
</Note>

## Messages worth recognising

<AccordionGroup>
  <Accordion title="403 { &#x22;error&#x22;: &#x22;Invalid API key&#x22; }" icon="key">
    Every credential refusal answers identically: unknown key, revoked key, expired key, wrong IP address, or a location the key does not cover. Work down the checklist in [Authentication](/api-reference/authentication#every-restriction-is-checked-per-request).
  </Accordion>

  <Accordion title="400 &#x22;Please include count, page and sorting query parameters.&#x22;" icon="list-ol">
    The visitor and registered-visitor lists require paging parameters. Add `count` and `page` — and, on registered visitors, at least one `sorting[field]`.
  </Accordion>

  <Accordion title="400 { &#x22;message&#x22;: &#x22;TRIAL_EXPIRED&#x22; }" icon="hourglass-end">
    The location is on an expired trial. Data endpoints stay closed until it is on a paid plan.
  </Accordion>

  <Accordion title="400 { &#x22;message&#x22;: &#x22;Dataset too large.&#x22; }" icon="file-excel">
    The visitor export is capped at 200 rows per call. Pass `count=200` with a `page`, or narrow the export with filters.
  </Accordion>

  <Accordion title="400 { &#x22;message&#x22;: &#x22;No data.&#x22; }" icon="file-circle-xmark">
    The export matched no visitors. Not a failure — there was simply nothing to write.
  </Accordion>

  <Accordion title="429 &#x22;Too many invalid API key attempts from this IP&#x22;" icon="gauge-high">
    Thirty refused credentials from one address inside fifteen minutes. Stop retrying, fix the key, and wait out the window — retrying with the same broken key only extends it.
  </Accordion>
</AccordionGroup>

## A note on 200s

A handful of older endpoints answer `200` with a message body instead of an error status — for example `{ "message": "company not found" }` or `{ "message": "No Known Visitor found!" }`. When you expect an object and get a body with only a `message` key, treat it as "not found".

## Retrying

* `500` is worth one or two retries with a short backoff.
* `400`, `401`, `403` and `404` never become successful on retry. Fix the request.
* `429` needs you to stop entirely for the window — further attempts keep it open.


## Related topics

- [Introduction](/api-reference/introduction.md)
- [Webhooks](/documentation/webhooks.md)
- [Replacing the host list](/api-reference/hosts/replacing-the-host-list.md)
- [Marking a visitor safe](/api-reference/visitors/marking-a-visitor-safe.md)
- [Marking a visitor not safe](/api-reference/visitors/marking-a-visitor-not-safe.md)