Rate Limits & Errors
Understand rate limiting, HTTP status codes, and error handling for the Auto Toon API.
Rate Limits
The Auto Toon API enforces a limit of 100 requests per minute per API key. Rate limit information is included in the response headers of every request.
| Header | Description | Example |
|---|---|---|
X-RateLimit-Limit | Maximum requests per minute | 100 |
X-RateLimit-Remaining | Requests remaining in current window | 97 |
X-RateLimit-Reset | Unix timestamp when the window resets | 1620000000 |
HTTP Status Codes
| Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Missing or invalid API key |
| 402 | Payment Required - Insufficient credits |
| 403 | Forbidden - Terms not accepted or feature not available |
| 404 | Not Found - Resource doesn't exist |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Internal Server Error |
Error Response Format
All error responses follow a consistent JSON structure. Additional fields may be included depending on the error type.
{
"error": "Human-readable error message",
"code": "ERROR_CODE"
}Common Error Codes
INSUFFICIENT_CREDITSThe account does not have enough credits for this operation.
{
"error": "Insufficient credits",
"code": "INSUFFICIENT_CREDITS",
"balance": 2,
"required": 3,
"needsTopUp": true
}TERMS_NOT_ACCEPTEDThe user must accept the terms of service before using this feature.
RATE_LIMITEDToo many requests. Includes a retryAfter field indicating seconds to wait.
{
"error": "Rate limit exceeded",
"code": "RATE_LIMITED",
"retryAfter": 12
}INVALID_API_KEYThe API key format is invalid or the key has been revoked.
SAFETY_BLOCKThe submitted content was flagged by safety filters and could not be processed.
Retry Strategy
For 429 and 500 errors, we recommend implementing exponential backoff with jitter. This prevents thundering herd problems when many clients retry simultaneously.
async function fetchWithRetry(url: string, options: RequestInit, maxRetries = 3) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const res = await fetch(url, options);
if (res.ok) return res;
if (attempt < maxRetries && (res.status === 429 || res.status >= 500)) {
const baseDelay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
const jitter = Math.random() * 1000;
await new Promise((r) => setTimeout(r, baseDelay + jitter));
continue;
}
throw new Error(`Request failed with status ${res.status}`);
}
}Respect retryAfter
429 response with a retryAfter field, always wait at least that many seconds before retrying.