Рекомендации

Практики для надёжной интеграции с Clipia API — идемпотентность на ретраях, вебхуки вместо опроса, обработка ошибок и 429 с backoff, оценка стоимости и хранение request_id.

Чтобы интеграция с Clipia API была надёжной и предсказуемой по стоимости, придерживайтесь пяти практик: делайте отправки идемпотентными, предпочитайте вебхуки опросу, обрабатывайте ошибки и 429 с экспоненциальной задержкой, оценивайте стоимость до отправки и сохраняйте request_id на своей стороне. Ниже — каждая практика отдельно.

Идемпотентность на ретраях

Передавайте Idempotency-Key (уникальный UUID v4 на каждый логический запрос) при каждой отправке. При сетевом сбое повторите запрос с тем же ключом и теми же параметрами — вернётся тот же request_id, без повторной генерации и повторного списания. Ключ хранится 24 часа.

curl -X POST https://api.clipia.ai/v1/models/nano-banana-2 \
  -H "Authorization: Bearer clipia_live_xxx" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 8f3a1c7e-2b41-4d2a-9c0e-1200304cf45b" \
  -d '{ "input": { "prompt": "a sunset over mountains, cinematic" } }'

Сценарий	Результат
тот же ключ + те же параметры	тот же `request_id`, без повторного списания
тот же ключ + другие параметры	`409 idempotency_key_reuse`
повтор, пока первый ещё обрабатывается	`409 request_in_progress`

Генерируйте ключ на логический запрос

Создавайте новый UUID v4 на каждую новую генерацию, а не на каждую сетевую попытку. Не кладите в ключ чувствительные данные (email и т.п.).

Вебхуки вместо опроса

Передавайте webhook_url при отправке — Clipia сам пришлёт POST по завершении, и опрашивать статус не придётся. Опрос (polling) держите как запасной вариант. Если опрашиваете — делайте это разумно (например, раз в 1–3 секунды), а не в плотном цикле.

Отвечайте 2xx в течение 10 секунд, иначе будет ретрай (до 6 попыток с экспоненциальной задержкой).
Проверяйте подпись X-Clipia-Signature (HMAC-SHA256) на каждой доставке.
Обрабатывайте доставки идемпотентно по request_id — возможна повторная доставка.

Обработка ошибок и 429 с backoff

Ошибки приходят в едином JSON-формате с полями error.type, error.code, error.message. Реагируйте по HTTP-коду.

HTTP	`code`	Что делать
`400` / `422`	`invalid_request` / `model_input_invalid`	исправить тело/параметры, не ретраить как есть
`401` / `403`	`invalid_api_key` / `insufficient_scope`	проверить ключ и scope
`402`	`insufficient_credits`	пополнить баланс
`429`	`rate_limit_exceeded`	подождать `Retry-After` секунд, затем повторить
`500` / `503`	`internal_error` / `service_unavailable`	ретрай с экспоненциальной задержкой

При 429 ориентируйтесь на заголовок Retry-After и метрики RateLimit-*:

RateLimit-Limit: 120
RateLimit-Remaining: 0
RateLimit-Reset: 37
Retry-After: 37

Экспоненциальная задержка с джиттером

Для 429, 500 и 503 повторяйте с растущей паузой и случайным джиттером (например 1с, 2с, 4с, 8с… плюс случайная добавка), чтобы не создавать всплесков. По умолчанию лимиты — 120 RPM и 10 параллельных генераций на ключ.

Оценка стоимости до отправки

Цена операции фиксирована и известна заранее. Чтобы узнать стоимость конкретного набора параметров без постановки в очередь, используйте POST /v1/models/{model}/estimate — он вернёт credits. Так можно показать стоимость пользователю или отсечь дорогие запросы заранее. При отправке цена дублируется в поле cost; при нехватке кредитов отправка вернёт 402.

Хранение request_id

Сохраняйте request_id каждой отправки в своей БД сразу после ответа submit. Он нужен, чтобы:

сопоставить пришедший вебхук с вашей сущностью;
опросить status_url / response_url при необходимости;
обеспечить идемпотентность на своей стороне (не обрабатывать одну доставку дважды).

Связка request_id ↔ Idempotency-Key

Храните пару Idempotency-Key → request_id: при потере ответа на submit повторный запрос с тем же ключом вернёт тот же request_id, и вы не создадите дубль генерации.