Errors & Rate Limits
KolWrite API errors use JSON responses with a stable code whenever the client can take action.
{
"detail": {
"code": "insufficient_scope",
"message": "This endpoint requires the 'jobs:write' scope",
"required_scope": "jobs:write"
}
}Common statuses
| Status | Meaning |
|---|---|
400 | Invalid input or unsupported option combination |
401 | Missing, invalid, expired, or revoked token |
403 | Token is valid but lacks scope or route access |
404 | Resource is missing or not visible to the token owner |
409 | Conflict, usually an idempotency or state transition issue |
422 | Request body shape is valid JSON but fails validation |
429 | Rate limit or credit reservation pressure |
5xx | Temporary KolWrite service error |
Retry guidance
Retry 429, 502, 503, and 504 with exponential backoff and jitter. Use Idempotency-Key on job creation so network retries never create duplicate jobs. Do not retry 401, 403, or validation errors until the token or request is corrected.
Rate-limit headers
Limits apply per credential. Responses include X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset; on 429, honor Retry-After before retrying.