> ## Documentation Index
> Fetch the complete documentation index at: https://docs.postsider.com/llms.txt
> Use this file to discover all available pages before exploring further.

# PostSider API Errors

> The HTTP status codes the PostSider public API returns, what triggers each one, and the shape of the error bodies.

The public API uses standard HTTP status codes plus the JSON `Authorization` header described in the [API overview](/api/overview). Most errors return a body with a `msg` field; plan and validation errors carry more structured fields.

## Status codes

| Code  | Meaning                       | Typical cause                                                                                                                                         |
| ----- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `400` | Invalid request               | Malformed body, a channel's content failing validation, or an invalid `status` value                                                                  |
| `401` | Missing or invalid credential | No `Authorization` header, an unknown key, an expired OAuth token, or no subscription row for the organization                                        |
| `402` | Plan limit reached            | Channel cap, monthly post quota, team seats, webhook count, or AI action limit exceeded; also returned when a plan does not include public API access |
| `403` | Forbidden                     | The caller's role does not allow the operation; note that the API remaps `403` to `401` in some flows                                                 |
| `404` | Not found                     | Unknown post, channel, or endpoint                                                                                                                    |
| `409` | Conflict                      | Idempotency-Key replay mismatch                                                                                                                       |
| `413` | Payload too large             | Upload exceeds the configured file-size limit                                                                                                         |
| `429` | Rate limited                  | More than 60 requests per minute for the organization; honor `Retry-After`                                                                            |
| `500` | Server error                  | Unexpected failure; retry, then check the logs                                                                                                        |

## Plan-limit (402) bodies

Limit responses include the affected section so clients can map them to friendly messages:

```json theme={null}
{ "statusCode": 402, "message": "Plan limit reached", "section": "posts_per_month" }
```

`sections`: `posts_per_month`, `channel`, `team_members`, `webhooks`, `ai`. A missing `public_api` entitlement also returns `402` at the auth boundary.

## Validation (400) bodies

Channel-level validation failures include which provider and channel failed:

```json theme={null}
{ "statusCode": 400, "provider": "x", "name": "My X", "message": "Content exceeds the 280 character limit" }
```

## Idempotency (409)

Replaying an `Idempotency-Key` with a different body for the same organization returns `409`. Replaying with the same key and body returns the original result.

## Rate limits (429)

```json theme={null}
{ "msg": "Too many requests", "retryAfter": 30 }
```

Wait `retryAfter` seconds before retrying. See [Rate limits](/api/overview) for the window semantics.

## SDK behavior

The `@postsider/node` SDK throws `PostsiderApiError` for every non-2xx response, with `status`, `method`, `path`, and the parsed response `details`.