To ensure optimal performance and availability for all users, the Vrio API implements intelligent rate limiting on certain endpoints. Our rate limiting system is designed to prevent resource-intensive broad queries while allowing unlimited targeted lookups using specific identifiers.

Why Rate Limiting Exists

Rate limiting protects our infrastructure and ensures consistent API performance for all customers by:

Preventing Resource Exhaustion - Broad queries without specific filters can scan large datasets and impact system performance
Ensuring Fair Access - Limits prevent any single integration from consuming disproportionate resources
Maintaining Response Times - By controlling concurrent heavy operations, we keep response times fast for everyone
Encouraging Best Practices - Rate limits guide developers toward efficient, targeted API usage patterns

How Rate Limiting Works

Our rate limiting system uses a concurrent request model rather than a traditional request-per-timeframe approach. Here's what that means:

Concurrent Request Limits

For affected endpoints, you can have up to 3 concurrent requests running at the same time within a 10-minute window. When a request completes, that slot becomes available again immediately.

Example:

Request 1 starts → count: 1
Request 2 starts → count: 2
Request 1 completes → count: 1
Request 3 starts → count: 2
Request 4 starts → count: 3
Request 5 starts → THROTTLED (limit reached)

Once Request 2 completes, you can make another request.

Smart Bypassing with Search Fields

The rate limiter intelligently distinguishes between expensive broad queries and efficient targeted lookups. Requests that include specific search parameters are not counted toward the rate limit.

This means you can make unlimited requests when searching by specific identifiers like customer IDs, order IDs, or transaction IDs.

Affected Endpoints

The following endpoints have rate limiting enabled with a limit of 3 concurrent requests within a 10-minute window:

Endpoint	Bypass Throttle By Searching With
`GET /transactions`	`transaction_id`, `transaction_charge_id`, `order_id`, `customer_id`
`GET /customers`	`customer_id`, `email`
`GET /line_items`	`transaction_id`, `order_id`, `customer_id`
`GET /order_offers`	`order_offer_id`, `customer_id`, `email`
`GET /orders`	`order_id`, `customer_id`, `customer_email`
`GET /sales`	`transaction_id`, `order_id`, `customer_id`
`GET /shipments`	`shipment_id`, `customer_id`, `order_id`, `shipment_tracking_id`

Avoiding Rate Limits

Best Practice: Use Specific Search Fields

Always include at least one of the required search fields when querying these endpoints. This ensures your request bypasses rate limiting entirely.

Throttled Request (counted toward limit):

GET https://api.vrio.app/transactions?date_complete_from=2024-01-01&date_complete_to=2024-01-31

Bypassed Request (not counted):

GET https://api.vrio.app/transactions?customer_id=12345&date_complete_from=2024-01-01&date_complete_to=2024-01-31

In the second example, including customer_id as a query parameter bypasses the rate limit because you're targeting a specific customer rather than scanning all transactions.

Efficient Pagination Strategies

When you need to retrieve large datasets:

Use webhook events - Subscribe to real-time webhooks instead of polling for changes
Query by specific IDs - Break broad queries into targeted lookups by customer, order, or transaction ID
Implement proper retry logic - If you do hit rate limits, implement exponential backoff in your retry mechanism
Cache responses - Store results locally to reduce the need for repeated API calls

Rate Limit Response

When you exceed the concurrent request limit, the API returns a 429 Too Many Requests response:

{
  "error": {
    "code": "too_many_requests",
    "message": "Too Many Requests"
  }
}

How to Handle 429 Responses

Implement retry logic with exponential backoff
Wait for existing requests to complete before retrying
Review your implementation to use specific search fields where possible
Contact support if you have legitimate use cases requiring higher limits

Need Higher Limits?

If your integration requires higher concurrent limits for legitimate use cases, please contact our support team at support@vrio.com with:

Your use case description
Expected query patterns and volume
Which endpoints you need increased limits for

We're happy to work with you to ensure your integration runs smoothly while maintaining system performance for all users.

Note: These rate limits are designed to ensure fair access for all customers. Attempts to circumvent these limits violate our terms of service. We actively monitor for such activity and reserve the right to disable API access for users who attempt to abuse or manipulate the system.