Rate limits
Sume applies rate limits per API key. Rate limits protect request pace and queue health; Sume credits remain the monthly generation quota.
Default limits
| Bucket | Endpoints | Burst limit | Sustained limit |
|---|---|---|---|
| Read | GET /v1/me, GET /v1/avatars/{id}, GET /v1/avatar-videos/{id} | 120 requests / minute | 10,000 requests / day |
| Generation | POST /v1/avatars, POST /v1/avatar-videos | 10 requests / minute | 300 requests / day |
Read endpoints do not charge credits. Generation endpoints must pass both the
rate limit check and the Sume credit check before a job is accepted. If your
workspace or owner account is out of credits, Sume returns
402 insufficient_credits. If your API key is sending requests too quickly,
Sume returns 429 rate_limit_exceeded.
Rate limit headers
Successful and rate-limited API responses include the active window headers:
| Header | Description |
|---|---|
RateLimit-Limit | Request limit for the active bucket window. |
RateLimit-Remaining | Requests remaining in that window. |
RateLimit-Reset | Seconds until the active window resets. |
Retry-After | Present on 429 responses. Seconds to wait before retrying. |
X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset are also
sent for compatibility with older API clients.
429 response
Wait for Retry-After seconds before retrying. Polling clients should use
backoff and avoid tight loops while waiting for jobs to become ready or
failed.