Rate limits & errors

Rate limiting on publishing, scope and plan errors, and general error-handling guidance.

This page covers how the Keryo API signals rate limits and errors, and how your integration should respond. It applies to both API keys and MCP OAuth 2.1 access tokens.

Rate limiting

Publishing and scheduling are rate-limited. If you call POST /posts/send/:id or PUT /posts/schedule/:id too frequently, the request is throttled.

• Back off and retry after a delay when you hit a rate limit.

• Batch or space out publishing rather than firing many requests at once.

• For failed publishes (not rate limits), a dedicated POST /posts/retry/:id endpoint exists to retry.

Publishing is irreversible. Confirm the target accounts and content before calling the publish endpoint, and don't blindly retry a publish that may have partially succeeded — check post status first.

Authorization errors

Scoped tokens (API keys and OAuth 2.1 access tokens) are checked on every request against both scopes and plan tier.

Status	When	What it means
401 Unauthorized	Missing or invalid token	The Authorization header is absent, malformed, expired, or the token is revoked. For the MCP server, a WWW-Authenticate challenge is returned so the client can discover the authorization server.
403 Forbidden	Missing scope or insufficient plan	The token authenticated successfully, but it lacks the scope the endpoint requires, or the account's plan tier is too low for the action (e.g. import below Freelance, statistics below Studio).

The difference matters when handling errors:

• 401 → fix authentication (send a valid token; re-run the OAuth flow for MCP).

• 403 → fix authorization (grant the missing scope, or upgrade the plan). Retrying the same request won't help.

Examples

Missing scope on a scoped token:

POST /posts/send/post_123
Authorization: Bearer <key-without-posts:publish>

HTTP/1.1 403 Forbidden

Statistics requested on a plan below Studio:

GET /statistics/linkedin
Authorization: Bearer <key-with-stats:read-but-Freelance-plan>

HTTP/1.1 403 Forbidden

Error response bodies are illustrative; rely on the HTTP status code for control flow.

General error handling

Follow standard HTTP status semantics:

• 2xx — success.

• 4xx — a problem with the request (authentication, authorization, validation, or a missing resource). Fix the request before retrying; retrying an unchanged 4xx generally won't succeed.

• 429 — you're being rate-limited (see above). Back off and retry later.

• 5xx — a server-side problem. Retry with backoff; if it persists, contact support.

Recommended integration practices:

1. Read the status code first, then the body for detail.

2. Distinguish 401 from 403 — one is an auth problem, the other a permissions/plan problem.

3. Back off on rate limits and 5xx, using exponential delays.

4. Never auto-retry a publish without checking the post's current status, since publishing is irreversible.

Related pages

• Authentication — scopes and plan-tier gating.

• API reference — the endpoints and their required scopes.

• MCP connector — the OAuth 2.1 401 / WWW-Authenticate flow.