Handle API errors, rate limits, and retries
What 401, 403, 409, 422, and 429 mean on Krevaya's API and MCP server, the shared limits, and when it's safe to retry
Written by the Krevaya team · Updated
Krevaya's REST API, MCP server, and GraphQL beta share one request budget per account, and every error says what to fix. Read the status and the message before you retry: most errors need a changed request, not a repeat.
Limits
| Limit | Value | What you get when you hit it |
|---|---|---|
| Requests | 120 per minute per account, shared by all your keys and by REST, MCP, and GraphQL | HTTP 429 with Retry-After: 60 |
| Generation | 40 requests per hour that use the Generate content permission | REST: 429 with Retry-After: 3600. MCP: a tool error |
| Posting limits | Per-account posting caps, and Krevaya's shared budget for metered platforms such as X | HTTP 429 with code posting_cap or platform_budget, next_window (UTC), and Retry-After when known |
| API keys | 10 active keys | 400 until you revoke one |
| Webhook endpoints | 5 | 400 |
| Video exports | One at a time per account | Wait for the current export |
A second key doesn't add a second allowance.
What each status means
| Status | Usual cause | What to do |
|---|---|---|
| 400 | Input Krevaya can't use: unknown brand, unsupported media, a URL that isn't public, text that failed safety screening, a Lineup with no connected channel | Fix the input from the message |
| 401 | Missing, mistyped, or revoked key; an expired sign-in; an inactive account | Check the stored key, or sign in again from your AI app |
| 403 | The key lacks a permission ("this key lacks the 'publish' scope"), your plan is below Plus, a plan limit, or a Pinterest or Tumblr approval | Create a key with the permission, upgrade, or approve those posts in Krevaya |
| 404 | The post, asset, or brand isn't in your account | Check the ID and brand |
| 409 | Another post from the same account already holds that minute on that platform; a stale version of a creation or brand memory; an Idempotency-Key reused with different content; a platform Krevaya has paused (code platform_paused) | Pick another minute, or re-read the current state and reapply your change |
| 410 | Automation requests only: the draft was deleted, or the events cursor expired | Follow the message |
| 422 | A field has the wrong type, is out of range, or is missing; text over a channel's limit | Fix the field the message names |
| 429 | A limit from the table above | Wait at least Retry-After, then back off with a little random delay |
| 502 | A Studio creation failed to render | Keep the draft's id and retry the render on it |
| 503 | A temporary outage, such as a busy job queue (Retry-After: 15) or AI generation paused | Try again later |
Text over a channel's limit is refused, never cut: X takes 280 characters, Bluesky 300, Threads 500, and LinkedIn 3,000, and any post's text is capped at 4,000. The message tells you the count, for example "Bluesky takes at most 300 characters, and this text has 342. Shorten it to post on Bluesky."
Read the right error format
- REST: the body has
detail, a sentence or, for 422, a list of field errors. Posting-limit 429s addcodeandnext_window. - MCP: a tool failure comes back as HTTP 200 with
result.isError: trueand a message. Protocol errors useerror. The request limit is a real HTTP 429. Check all three before reporting success. - GraphQL: failures can also be HTTP 200 with an
errorsarray. - 201 with
render_error: the draft exists but its picture didn't render. Don't create another draft; retry the render on that id.
Retry safely
- Throttled reads: honor
Retry-Afterand add a small random delay so workers don't restart together. - Validation or permission errors: change the request or the key first. Repeating won't help.
- A write that timed out: check whether it happened before repeating it.
POST /v1/postsaccepts anIdempotency-Keyheader (withbrand_id): repeating the same request returns the original post, markedidempotency_replayed: true, instead of a duplicate. - Generation and media uploads (
/v1/generate,repurpose,draft_week, asset imports) have no such protection. Don't retry them automatically, or you may get extra drafts and spend credits twice. - Long jobs: keep the
job_idand polljob_status. Your client's timeout doesn't cancel the job. - Stale versions: read the latest version and reapply only your change. Bumping the version number on old data can overwrite someone else's work.
When you contact support, include the method and path or tool name, the status, the message, and the IDs involved. Never include API keys or webhook secrets.