Developer REST API
Rate Limits & Error Handling
Understand API status codes, rate limiting headers, and recommended retry strategies.
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();
}
}