Browse docs
Social media API rate limit headers#
How usage is charged#
A single request is one unit. A batch request (POST /posts/bulk with N items) charges N units. A bulk target action counts the destinations it touches — canceling 500 post targets in one call uses 500 units against the write budget, not 1. A token is only ever charged for what it could actually do: a call a token's scope or role doesn't allow costs the ordinary one unit, not the batch size, since a read-only token can't accidentally exhaust the budget other tokens share.
The MCP server has its own separate shared budget per connected client, with a tighter share reserved for destructive tools (delete/cancel/bulk-cancel). The API surface and the MCP surface do not share one budget — a cap on one doesn't throttle the other.
{
"type": "https://skedcast.com/errors/rate_limited",
"title": "Rate limited",
"status": 429,
"category": "rate-limit",
"code": "rate_limited",
"correlationId": "c-…"
}Retrying correctly#
Every mutating request carries an Idempotency-Key, so retrying the exact same request after a timeout or a 5xx is always safe — you'll get the original result back, never a duplicate post. On a 429, honor Retry-After rather than retrying immediately; a refused request still counts toward your plan's overall budget, so hammering it makes recovery slower, not faster.
- 400 / 422 — fix the request; retrying unchanged will fail the same way.
- 401 — check the Authorization header and whether the key/token is still valid.
- 403 — the token's scope or the owning member's role doesn't allow this action.
- 409 — a conflict (idempotency key reuse with a different body, or a state conflict); inspect before retrying.
- 429 — back off per Retry-After.
- 5xx — transient; safe to retry with backoff, same Idempotency-Key.
FAQ
- Does a rate-limited request against MCP affect my REST API budget?
- No — the REST API and the MCP server have separate, independently-tracked budgets for the same client, so hitting one limit doesn't throttle the other surface.
- Can I raise my rate limit without upgrading my plan?
- The per-minute budget is set by your plan. You can only tighten it further for a specific key or connected app (a write-only cap), never raise it above your plan's ceiling.