Developer REST API
Rate Limits & Error Handling
Understand API status codes, rate limiting headers, and recommended retry strategies.
Rate Limits & Error Handling
ZyVOP utilizes standard HTTP response codes and headers to communicate request outcomes and enforce rate constraints.
HTTP Status Codes
| Code | Status | Meaning |
|---|---|---|
200 | OK | Existing article updated in place |
201 | Created | New article published successfully |
400 | Bad Request | Malformed request body, unparsable frontmatter, or missing title |
401 | Unauthorized | Missing or invalid Authorization: Bearer zv_... token |
429 | Too Many Requests | You exceeded the rate limit threshold |
500 | Internal Server Error | Transient backend issue; safe to retry with backoff |
Rate Limits
Developer API requests are metered per developer token:
- Limit: 10 requests per minute (60,000 ms sliding window)
Rate Limit Headers
Every response from /api/v1/articles includes current quota headers:
HTTP/1.1 200 OK
X-RateLimit-Limit: 10
X-RateLimit-Remaining: 8
X-RateLimit-Reset: 42100| Header | Description |
|---|---|
X-RateLimit-Limit | Maximum number of allowed requests in the 1-minute window (10) |
X-RateLimit-Remaining | Remaining requests available in the current window |
X-RateLimit-Reset | Time in milliseconds until quota resets |
Retry-After | When blocked (429), the number of milliseconds to wait before retrying |
429 Too Many Requests Example
When quota is exceeded, the server responds with:
HTTP/1.1 429 Too Many Requests
Retry-After: 32000
Content-Type: application/json
{
"statusCode": 429,
"message": "ThrottlerException: Too Many Requests"
}Recommended Retry Strategy
When publishing automated batches from build scripts or CI pipelines:
- Add a delay between posts: Space automated article updates by at least 6 seconds.
- Respect
Retry-After: If receiving a429, parse the header and pause execution before retrying. - Use Exponential Backoff:
async function publishWithRetry(payload, maxAttempts = 3) {
for (let attempt = 1; attempt <= maxAttempts; attempt++) {
const res = await fetch('https://zyvop.com/api/v1/articles', {
method: 'POST',
headers: {
'Authorization': `Bearer ${process.env.ZYVOP_TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify(payload),
});
if (res.status === 429) {
const retryAfter = Number(res.headers.get('Retry-After')) || 60000;
console.warn(`Rate limited. Waiting ${retryAfter}ms before retry ${attempt}...`);
await new Promise(r => setTimeout(r, retryAfter));
continue;
}
return res.json();
}
}