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

# Retries, limits, and errors

> Recover from failures without creating duplicate work.

## Idempotent creation and publication

`POST /posts` and `POST /posts/POST_ID/publish` accept an optional `Idempotency-Key` header. Use 1–128 letters, digits, underscores, periods, or hyphens.

Reuse the same key and payload for the same logical operation for up to 24 hours. A replay returns the original data and HTTP status. Reusing a key with different input returns `409`; a concurrent request can return `idempotency_in_progress` with `Retry-After: 1`.

CLI can generate a key, but an explicit key is easier to persist across job retries. MCP create, schedule, and publish tools require one.

## Rate limits

Limits are shared by all keys in the project. The default configuration is 120 total requests and 30 writes per minute; deployments can configure different limits. Read `X-RateLimit-Limit` and `X-RateLimit-Remaining` when provided. On `429`, wait for the `Retry-After` duration before retrying.

## Error responses

```json theme={null}
{
  "error": { "code": "insufficient_permissions", "message": "The API key lacks the required permissions." },
  "meta": { "requestId": "request-identifier" }
}
```

| Status | Next action |
| - | - |
| `400` | Correct the input or platform-specific requirements |
| `401` | Check the key, expiry, or CLI login |
| `403` | Check permissions; resume a key if the code is `api_key_paused` |
| `404` | Verify the resource ID and authorized project |
| `409` | Refresh changed state, or retry the same in-progress idempotent request after the indicated wait |
| `413` | Reduce the JSON body; upload file bytes directly to storage |
| `429` | Wait for `Retry-After` |
| `500`, `503` | Inspect state before retrying writes; retain the request ID |

JSON bodies are limited to 100 KB. Rejections before the controller may not use the public error envelope.

## Uncertain outcomes

An interrupted request can have succeeded. Reuse the original key for supported idempotent operations. For media creation, editing, or deletion, inspect the resource before retrying. Uploading the same file again creates a new media reservation.

The CLI's `doctor` checks runtime, connectivity, authentication, and effective permissions. Include the request ID when reporting an API issue.


## Related topics

- [Automate with the CLI](/cli/automation.md)
- [Request immediate publication](/api-reference/posts/request-immediate-publication.md)
- [Create a draft or scheduled post](/api-reference/posts/create-a-draft-or-scheduled-post.md)
- [Delete a post](/api-reference/posts/delete-a-post.md)
- [List posts](/api-reference/posts/list-posts.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.