Response Size Limits

The Vrio API has a maximum response size of approximately 6 MB. This is a hard infrastructure limit, not a configurable setting, and it applies to every endpoint. Broad queries against large datasets can produce a result set that exceeds it — in nearly all cases a request using several with expansions on a full page of records.

Because limit already caps every request at 200 records, the number of records you receive is bounded. What is not bounded is how large each of those records is — and that is controlled almost entirely by the with parameter. If you are seeing a 413, your expansions are the first and usually the only place to look.

When that happens, the API returns a 413 Payload Too Large response telling you the query was too broad, so you can narrow it and retry.

Why the Limit Exists

This limit works alongside rate limiting to keep the API fast and available for everyone. Both are pushing you in the same direction: query for the data you actually need, not everything at once.

The 413 Response

When a response exceeds the limit, you receive:

{
  "error": {
    "code": "response_limit_exceeded",
    "message": "The requested response exceeds the maximum supported response size (approximately 6 MB). Narrow your request by applying filters, reducing the date range, or requesting fewer records."
  }
}

The HTTP status code is 413.

This is not a transient error. Retrying the same request will produce the same result every time. The request has to change before it will succeed.

Staying Within the Limit

Use limit and offset to Paginate

The most direct fix. Instead of pulling an entire result set in one request, page through it:

GET https://api.vrio.app/transactions?date_created_from=2026-01-01&date_created_to=2026-01-31&limit=200&offset=0
GET https://api.vrio.app/transactions?date_created_from=2026-01-01&date_created_to=2026-01-31&limit=200&offset=200
GET https://api.vrio.app/transactions?date_created_from=2026-01-01&date_created_to=2026-01-31&limit=200&offset=400

limit has a maximum of 200 records per request. That ceiling is not by itself a guarantee you will stay under 6 MB — a full page of 200 records can still exceed the limit once expansions are involved.

There is no single correct page size below that maximum, since it depends on how much data each record carries for your account. If you are receiving 413 responses at limit=200, cut it in half and try again.

Query by Specific Identifiers

When you know what you are looking for, ask for it directly. Filtering by customer_id, order_id, or transaction_id returns a handful of records instead of a full page, and has the added benefit of bypassing rate limiting entirely.

GET https://api.vrio.app/orders?customer_id=12345

Note that narrowing a date range does not reduce the size of any individual response. Because limit caps every request at 200 records, a one-week query and a one-month query both return at most 200 records — the shorter range simply spans fewer pages. Date filters are for selecting the data you want, not for controlling response size.

Reduce Expanded Data with with

This is usually the single biggest factor in response size.

The with parameter expands each record to include its related data. Unlike limit, which controls how many records you get, with controls how large each record is — and it applies to every record in the result set.

GET https://api.vrio.app/orders?with=customer,order_offers,transactions,shipments

On a full page of 200 orders, that request does not return 200 orders. It returns 200 orders plus every customer record, every offer, every transaction, and every shipment attached to them. This is why the 200-record cap is not a guarantee: a page size that is perfectly safe with no expansions can exceed 6 MB several times over once a few are added.

Each endpoint supports its own set of expansions, and they are additive — with=customer,order_offers returns both. A few of the heaviest on GET /orders:

Request only the expansions your integration actually reads. If you are consuming three fields off customer and ignoring the rest, that is still the entire customer record on the wire for every order in the page. It is often cheaper to drop the expansion and fetch the handful of related records you need by ID.

Expansions and page size have to be tuned together: if you need heavy expansions, lower your limit to compensate.

Use Webhooks for Ongoing Sync

If you are polling for changes, webhook events are a better fit than repeatedly querying large date ranges. You receive changes as they happen instead of pulling the full dataset to find what moved.

Handling 413 in Your Integration

1. Treat 413 as a request problem, not a server problem. It means "ask for less," not "try again later." Do not route it into your generic retry logic.
2. Check your with parameter first. With page size already capped at 200, expansions are what pushed the response over. Removing a single unused expansion frequently drops it back under the limit on its own, without reducing the number of records you receive — which makes it the cheapest fix available.
3. Then reduce limit. If the request still exceeds the limit with expansions trimmed, halve your limit and reissue, repeating until it succeeds. This costs you more round trips for the same data, which is why it comes second.
4. Log the request that triggered it. Capture both limit and with — together they tell you where your integration is over-fetching.
5. Set a default limit that suits your expansion set. Rather than reacting to 413 responses, pick a page size up front that fits the expansions you use. A request pulling several heavy expansions may need a page well below the 200 maximum; a bare request can usually run at 200.