Ошибки и лимиты

Ошибка всегда приходит с правильным HTTP-кодом и понятным телом — с полем, которое не понравилось.

Формат

HTTP/1.1 400 Bad Request
{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_parameter",
    "message": "Amount is outside configured limits",
    "field": "amount"
  }
}

Коды

HTTP	code	Что делать
400	`invalid_parameter`	Исправьте поле из `field`
400	`invalid_webhook_url`	Нужен публичный HTTPS-адрес на 443 порту
400	`webhook_not_configured`	Сначала задайте адрес: `PUT /v1/webhook`
401	`missing_api_key` · `invalid_api_key`	Проверьте ключ; возможно, его перевыпустили или приложение приостановлено
404	`invoice_not_found`	Счёт не найден в этом приложении
409	`order_conflict`	Этот `order_id` уже занят счётом с другой суммой
409	`idempotency_conflict`	`Idempotency-Key` уже использован с другим телом
409	`invoice_not_cancellable`	Счёт уже оплачен, истёк или отменён
409	`conflict`	Например, приложение приостановлено в боте
429	`rate_limited`	Подождите `Retry-After` секунд
503	`rate_unavailable`	Счёт в валюте: курс временно недоступен — повторите через минуту

Лимиты

⏱ 120 запросов в минуту

На один ключ. При превышении — 429 и заголовок Retry-After.

⌛ Срок счёта

От 1 минуты до 7 дней, по умолчанию 1 час.

💰 Сумма

Минимум и максимум по монетам — в GET /v1/currencies.

📝 Длина полей

description до 1024, payload до 4096, order_id до 128 символов.

Советы

Ловите ошибки по code, а не по тексту message — текст может меняться.
При 5xx и сетевых ошибках повторяйте запрос с тем же Idempotency-Key — SDK делают это сами.
Сохраняйте order_id до запроса: тогда после сбоя счёт можно найти через GET /v1/invoices?order_id=….