Ошибки

Любая ошибка API — HTTP-код по классу ошибки и тело одной формы. Решение принимайте по kind (что делать) и code (почему), а не по тексту message: текст может меняться.

HTTP/1.1 429 Too Many Requests
Retry-After: 12
X-Request-Id: a1b2c3d4e5f60718

{"ok": false,
 "error": {"kind": "too_often", "code": "too_often", "message": "лимит ключа в минуту",
           "retry_after": 12},
 "request_id": "a1b2c3d4e5f60718"}

• kind, code, message, retry_after есть всегда (могут быть null). По месту бывают fields (какие поля не разобрались), missing (каких прав не хватает), vk_error (ошибка ВКонтакте как есть), cursor и count (докуда дошёл поток).
• request_id — тот же, что в заголовке X-Request-Id. Называйте его, когда пишете в поддержку.
• На 429 и 503 с retry_after тот же срок приходит заголовком Retry-After; на 401 — WWW-Authenticate: Bearer.
• Ошибки разбора тела — 400 caller_error, code=bad_args со списком fields, а не 422.
• Ошибка посреди потока NDJSON — последняя строка {"error": {…, "cursor", "count"}}: продолжите с cursor.

Классы ошибок

Частые коды

caller_error · 400

auth_failed · 401 / 403

payment_required · 402

not_found · 404

no_data · 404

conflict · 409

no_free_accounts · 409

account_lost · 410

unavailable · 503

Как повторять

• Повторяйте только то, где это помогает: 429, 502, 503, 409 no_free_accounts, 409 idempotency_in_progress — не раньше retry_after. Добавьте к паузе немного случайности, чтобы повторы нескольких процессов не совпали. Если 502 и 503 идут подряд, загляните на страницу состояния сервиса: там видно, известен ли сбой и когда он начался.
• 400, 401, 402, 403, 404 повтором не лечатся: нужно исправить запрос, ключ или тариф.
• Повтор действия (задача, подписка) — с тем же Idempotency-Key: тогда оно не выполнится дважды (подробнее).
• Незнакомый kind обрабатывайте как platform_unknown: новые классы могут появиться без смены версии.