Идемпотентность#

Сеть ненадёжна: ответ на POST /v1/posts мог потеряться, и вы не знаете, создан ли пост. Повторить запрос без защиты — значит рискнуть получить два одинаковых поста. Заголовок Idempotency-Key делает повтор безопасным.

Правила#

• Idempotency-Key обязателен на каждом POST в /v1 (посты, медиа, каналы, проверка, повтор цели). Без него — 400 idempotency_key_required.
• Ключ — любая строка от 1 до 255 печатных ASCII-символов без пробелов; удобнее всего UUID.
• Тот же ключ и то же тело → вы получите прежний ответ (с тем же статусом и телом) и заголовок Idempotent-Replayed: true. Второй пост не создаётся.
• Тот же ключ, другое тело → 422 idempotency_key_reused: ключ уже связан с другим запросом.
• Ключ действует 72 часа. Ключи разных API-ключей не пересекаются.
• Запоминаются только успешные ответы (2xx). Если запрос завершился ошибкой (например, 422 из-за подписи), тот же ключ можно использовать для исправленного запроса.

Как пользоваться#

1. Перед отправкой сгенерируйте ключ и сохраните его вместе с задачей (в базе, в очереди), а не только в памяти.
2. Если ответа нет (таймаут, обрыв), повторите запрос с тем же ключом и тем же телом: либо пост создастся, либо вы получите уже созданный.
3. Для нового поста берите новый ключ.

KEY=$(uuidgen)
curl -X POST https://castbase.ru/v1/posts -H "Idempotency-Key: $KEY" ...   # ответ потерян
curl -X POST https://castbase.ru/v1/posts -H "Idempotency-Key: $KEY" ...   # тот же результат, без дубля

external_ref#

external_ref — второй уровень защиты, уже на уровне вашей предметной области: уникальный в проекте идентификатор поста (например, social_post:42). Повторный POST с тем же external_ref вернёт 409 external_ref_taken, и в detail будет id уже созданного поста. Если пост отменить, external_ref освобождается.

Используйте оба: Idempotency-Key защищает от повторов одного запроса, external_ref — от повторной постановки той же задачи другим запросом.

MCP#

В MCP заголовок Idempotency-Key не используется. Подробности — в разделе MCP.