Rate Limits
Understanding and working within VasBox API rate limits.
To ensure fair usage and system stability, the VasBox API implements rate limiting. Understanding these limits helps you build robust integrations.
Rate Limits
Rate limits vary by endpoint and plan. Here are the default limits:
| Plan | Requests/min | Burst Limit |
|---|---|---|
| Free | 60 | 10 |
| Starter | 300 | 50 |
| Professional | 1,000 | 100 |
| Enterprise | Custom | Custom |
Endpoint-Specific Limits
Some endpoints have additional limits:
| Endpoint | Limit | Reason |
|---|---|---|
| POST /v1/invoices/*/submit | 10/min | ZIMRA submission throttling |
| POST /v1/receipts | 100/min | POS transaction limit |
| GET /v1/reports/* | 5/min | Resource-intensive queries |
Rate Limit Headers
Every API response includes headers to help you track your rate limit status:
| Header | Description |
|---|---|
| X-RateLimit-Limit | Maximum requests allowed per window |
| X-RateLimit-Remaining | Requests remaining in current window |
| X-RateLimit-Reset | Unix timestamp when the window resets |
| Retry-After | Seconds to wait before retrying (on 429) |
Rate Limit Response
When you exceed the rate limit, you'll receive a 429 response:
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1705320000
Retry-After: 45
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Please retry after 45 seconds.",
"request_id": "req_abc123"
}
}
Handling Rate Limits
Implement retry logic with exponential backoff to handle rate limits gracefully:
PHP
<?php
use VasBox\VasBox;
use VasBox\Exceptions\RateLimitException;
$vasbox = new VasBox(env('VASBOX_API_KEY'));
function createInvoiceWithRetry($vasbox, $data, $maxRetries = 3) {
$attempt = 0;
while ($attempt < $maxRetries) {
try {
return $vasbox->invoices->create($data);
} catch (RateLimitException $e) {
$attempt++;
if ($attempt >= $maxRetries) {
throw $e;
}
// Wait for the specified retry time
sleep($e->getRetryAfter());
}
}
}
JavaScript
import { VasBox, RateLimitError } from '@vasbox/sdk';
const vasbox = new VasBox(process.env.VASBOX_API_KEY);
async function createInvoiceWithRetry(data, maxRetries = 3) {
let attempt = 0;
while (attempt < maxRetries) {
try {
return await vasbox.invoices.create(data);
} catch (error) {
if (error instanceof RateLimitError) {
attempt++;
if (attempt >= maxRetries) {
throw error;
}
// Wait for the specified retry time
await new Promise(r =>
setTimeout(r, error.retryAfter * 1000)
);
} else {
throw error;
}
}
}
}
Best Practices
Follow these practices to work efficiently within rate limits:
Use Batch Operations
When creating multiple resources, use batch endpoints where available to reduce the number of API calls.
Cache Responses
Cache frequently accessed data like product lists and customer details to reduce redundant API calls.
Use Webhooks
Instead of polling for status updates, use webhooks to receive real-time notifications when resources change.
Monitor Your Usage
Track the rate limit headers in your responses to understand your usage patterns and avoid hitting limits.