Browse docs
Rate limit headers#
How usage is charged#
Each request costs one unit, with these exceptions:
- A batch request (
POST /v1/posts/bulkwith N items) costs N units. - A bulk action on targets costs one unit per destination it touches. Canceling 500 post targets in one call costs 500 units.
- A call the token's scope or role doesn't allow costs one unit, whatever the batch size, so a read-only token can't use up the budget other tokens share.
The MCP server has its own budget per connected client, and destructive tools (delete, cancel, bulk cancel) get a tighter share of it. The API and MCP budgets are separate: a cap on one doesn't throttle the other.
{
"type": "https://skedcast.com/errors/rate_limited",
"title": "Too many requests",
"status": 429,
"category": "rate-limit",
"code": "rate_limited",
"detail": "You are going too fast. Please slow down and try again.",
"correlationId": "c-…"
}Retrying correctly#
Every mutating request carries an Idempotency-Key, so a retry never creates a duplicate post. Retry a 429, 502, 503 or 504, or a request that got no response, with the same Idempotency-Key: SkedCast runs it once or returns the first result. Every other answer, including a 500, is kept for 24 hours and returned again for that key, so send a new key to try again. On a 429, wait for Retry-After instead of retrying immediately. A refused request still counts toward your budget, so hammering makes recovery slower, not faster.
- 400 / 422: fix the request. Retrying it unchanged fails the same way.
- 401: check the Authorization header and whether the key or token is still valid.
- 403: the token's scope or the owning member's role doesn't allow this action.
- 409: a state conflict, or a request with the same Idempotency-Key still running (
idempotency_in_progress, wait forRetry-After). Inspect before retrying. - 422
idempotency_key_reuse: the key was already used with a different body. Use a new key. - 429: wait for Retry-After.
429 platform_capacity_exhaustedand429 youtube_units_exhaustedmean a platform is temporarily at its limit. Retry after the wait inRetry-After. - 502, 503 or 504: transient. Retry with backoff and the same Idempotency-Key. 500: the answer is kept for that key, so retry with a new key.
FAQ
- Does a rate-limited request against MCP affect my REST API budget?
- No. The REST API and the MCP server have separate budgets for the same client, so hitting one limit doesn't throttle the other.
- Can I raise my rate limit without upgrading my plan?
- No. The per-minute budget is set by your plan. In Settings → Developer you can set a lower write limit on a key or a connected app. You cannot raise it above your plan's budget.