beast docs

Ошибки

Любой ответ API это JSON. Ошибка несёт код и иногда пояснение.

{"error": "bad_request", "message": "body must be JSON"}

Опирайтесь на error. Текст message для человека, он может меняться.

Коды

HTTPerrorКогдаЧто делать
400bad_requestТело не JSON или больше 8 КиБ. Поле не того типа, например сумма числом, а не строкой: тогда message называет поле. Сеть не trc20/bep20. Сумма не по формату, ноль или больше 1000000. external_id пустой, длиннее 128 байт или с управляющими символами. ttl вне 300..MAX_TTL (по умолчанию 86400).Исправить запрос. Повтор не поможет.
401unauthorizedНет заголовка Authorization: Bearer или токен не тот.Проверить токен и API_TOKEN_SHA256.
404not_foundСчёта с таким id нет, id не похож на inv_ и 24 hex, или такого пути нет вовсе.Проверить id.
405method_not_allowedИзвестный путь, но не тот метод. Например GET /v1/invoices.Взять метод из справочника.
409external_id_conflictexternal_id уже занят счётом с другой сетью или суммой.Взять новый external_id или прежние сеть и сумму.
429too_many_open_invoicesВ этой сети уже MAX_OPEN_INVOICES открытых неистёкших счетов (по умолчанию 200).Повторить позже. Или поднять лимит, если нагрузка настоящая.
500internalСбой на стороне сервиса, например база.Повторить с тем же external_id: это безопасно.

Поле не того типа:

amount has the wrong type: amount, network and external_id are strings (amount like "9.99"), ttl is an integer

Неверное значение. Сообщение одно на все поля, в конце ваш MAX_TTL:

network trc20|bep20, amount like "9.99" (max 6 decimals, 0 < amount <= 1000000), external_id 1-128 printable chars, ttl 300-86400 s

Особые случаи

ГдеОтвет
Любой путь вне /pay/ без верного токена401 {"error":"unauthorized"}, даже если пути нет.
Неизвестный путь или метод с верным токеном404 {"error":"not_found"} или 405 {"error":"method_not_allowed"}.
/pay/{id} на неизвестный счёт404, текст «Счёт не найден».
/pay/{id}/status на неизвестный счёт404 {"error":"not_found"}.
/pay/{id}/status на закрытый счёт200 со status: "closed". Закрыт значит не оплачен и окно наблюдения кончилось: 7 дней после expires_at, 1 день, если не пришло ничего.
/pay/{id}/qr.png на неизвестный или закрытый счёт404 текстом.
Слишком частые запросы к /pay/429 от nginx, если вы поставили лимит.

Что повторять

  • 500, обрыв, таймаут: повторять с тем же телом. Создание счёта идемпотентно по external_id.
  • 429: повторять позже, когда часть счетов оплатят или они истекут. Повтор с тем же external_id уже созданного счёта вернёт его и при лимите.
  • 400, 401, 404, 405, 409: не повторять, а чинить.