Ошибки
Любой ответ API это JSON. Ошибка несёт код и иногда пояснение.
{"error": "bad_request", "message": "body must be JSON"}
Опирайтесь на error. Текст message для человека, он может меняться.
Коды
| HTTP | error | Когда | Что делать |
|---|---|---|---|
| 400 | bad_request | Тело не JSON или больше 8 КиБ. Поле не того типа, например сумма числом, а не строкой: тогда message называет поле. Сеть не trc20/bep20. Сумма не по формату, ноль или больше 1000000. external_id пустой, длиннее 128 байт или с управляющими символами. ttl вне 300..MAX_TTL (по умолчанию 86400). | Исправить запрос. Повтор не поможет. |
| 401 | unauthorized | Нет заголовка Authorization: Bearer или токен не тот. | Проверить токен и API_TOKEN_SHA256. |
| 404 | not_found | Счёта с таким id нет, id не похож на inv_ и 24 hex, или такого пути нет вовсе. | Проверить id. |
| 405 | method_not_allowed | Известный путь, но не тот метод. Например GET /v1/invoices. | Взять метод из справочника. |
| 409 | external_id_conflict | external_id уже занят счётом с другой сетью или суммой. | Взять новый external_id или прежние сеть и сумму. |
| 429 | too_many_open_invoices | В этой сети уже MAX_OPEN_INVOICES открытых неистёкших счетов (по умолчанию 200). | Повторить позже. Или поднять лимит, если нагрузка настоящая. |
| 500 | internal | Сбой на стороне сервиса, например база. | Повторить с тем же 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: не повторять, а чинить.