> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/developers/rate-limits-and-errors.md).

# 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.

{% hint style="warning" %}
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.
{% endhint %}

## 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). |

{% hint style="info" %}
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.
  {% endhint %}

### Examples

Missing scope on a scoped token:

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

HTTP/1.1 403 Forbidden
```

Statistics requested on a plan below Studio:

```http
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](/keryo-docs/developers/authentication.md) — scopes and plan-tier gating.
* [API reference](/keryo-docs/developers/api-reference.md) — the endpoints and their required scopes.
* [MCP connector](/keryo-docs/developers/mcp-connector.md) — the OAuth 2.1 `401` / `WWW-Authenticate` flow.