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

LimitValueWhat you get when you hit it
Requests120 per minute per account, shared by all your keys and by REST, MCP, and GraphQLHTTP 429 with Retry-After: 60
Generation40 requests per hour that use the Generate content permissionREST: 429 with Retry-After: 3600. MCP: a tool error
Posting limitsPer-account posting caps, and Krevaya's shared budget for metered platforms such as XHTTP 429 with code posting_cap or platform_budget, next_window (UTC), and Retry-After when known
API keys10 active keys400 until you revoke one
Webhook endpoints5400
Video exportsOne at a time per accountWait for the current export

A second key doesn't add a second allowance.

What each status means

StatusUsual causeWhat to do
400Input Krevaya can't use: unknown brand, unsupported media, a URL that isn't public, text that failed safety screening, a Lineup with no connected channelFix the input from the message
401Missing, mistyped, or revoked key; an expired sign-in; an inactive accountCheck the stored key, or sign in again from your AI app
403The key lacks a permission ("this key lacks the 'publish' scope"), your plan is below Plus, a plan limit, or a Pinterest or Tumblr approvalCreate a key with the permission, upgrade, or approve those posts in Krevaya
404The post, asset, or brand isn't in your accountCheck the ID and brand
409Another 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
410Automation requests only: the draft was deleted, or the events cursor expiredFollow the message
422A field has the wrong type, is out of range, or is missing; text over a channel's limitFix the field the message names
429A limit from the table aboveWait at least Retry-After, then back off with a little random delay
502A Studio creation failed to renderKeep the draft's id and retry the render on it
503A temporary outage, such as a busy job queue (Retry-After: 15) or AI generation pausedTry 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 add code and next_window.
  • MCP: a tool failure comes back as HTTP 200 with result.isError: true and a message. Protocol errors use error. The request limit is a real HTTP 429. Check all three before reporting success.
  • GraphQL: failures can also be HTTP 200 with an errors array.
  • 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-After and 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/posts accepts an Idempotency-Key header (with brand_id): repeating the same request returns the original post, marked idempotency_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_id and poll job_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.

Did this answer your question?