Ошибки

Единый конверт ошибок и все восемь кодов: когда возникает каждый и как его обрабатывать.

Любая ошибка — валидация, авторизация, троттлинг, внутренний сбой — возвращает один и тот же JSON-конверт. Кодов ровно восемь; в error.code никогда не появится ничего другого, поэтому можно смело строить switch по нему.

Конверт ошибки

{
  "error": {
    "code": "rate_limited",
    "message": "rate limit exceeded (invoices: 30/min); retry later",
    "doc_url": "https://zerokyc-payments.com/docs/errors#rate_limited"
  }
}

code — один из восьми машиночитаемых кодов ниже.
message — человекочитаемое описание, его безопасно логировать и показывать в своих дашбордах. При ошибках валидации содержит первую непрошедшую проверку, например ttl_minutes must be between 10 and 4320.
doc_url — прямая ссылка на соответствующий раздел этой страницы.

Коды кратко

Код	HTTP	Когда возникает
`invalid_request`	400	Тело или параметры запроса не прошли валидацию
`unauthorized`	401	Ключ API отсутствует, битый или неизвестен
`account_suspended`	402	Биллинговая суспензия — создание инвойсов заблокировано
`forbidden`	403	Ключ отозван или аккаунт архивирован
`not_found`	404	Объекта нет (или он принадлежит другому мерчанту/режиму)
`idempotency_conflict`	409	Тот же `Idempotency-Key` использован с другим телом
`rate_limited`	429	Превышен лимит на ключ
`internal_error`	500	Неожиданный сбой на нашей стороне — ретрай с бэкоффом

`invalid_request`

HTTP 400. Валидация тела, значения вне диапазона или операция, недопустимая для текущего состояния инвойса (например, отмена уже подтверждённого инвойса). Исправьте запрос: неизменённый ретрай упадёт так же.

`unauthorized`

HTTP 401. Заголовок Authorization: Bearer … отсутствует, битый или ключ неизвестен. Проверьте префикс: pk_live_… / pk_test_…. Учтите: валидный ключ pk_test_… не увидит live-инвойсы — они для него вернутся как not_found.

`account_suspended`

HTTP 402. Подписка в суспензии (платформенный инвойс не оплачен после grace-периода). Создание новых инвойсов возвращает этот код до погашения; существующие инвойсы, чекаут и вебхуки продолжают работать. Подробности: Direct-касса — биллинг.

`forbidden`

HTTP 403. Ключ API отозван в кабинете или аккаунт архивирован после долгой суспензии. Выпустите действующий ключ в разделе API-ключи.

`not_found`

HTTP 404. Id не существует, принадлежит другому мерчанту или живёт в другом режиме: ключи pk_test_… видят только sandbox-инвойсы, pk_live_… — только live. Неожиданный 404 на заведомо существующем инвойсе в первую очередь означает несовпадение режима.

`idempotency_conflict`

HTTP 409. Вы повторно использовали Idempotency-Key с другим телом запроса в пределах 24-часового окна. Либо отправьте то же тело, либо возьмите новый ключ. Полная семантика: Лимиты и идемпотентность.

`rate_limited`

HTTP 429. Превышен лимит на ключ для этого scope. Ответ несёт Retry-After: <секунды> и стандартные заголовки X-RateLimit-* — ориентируйтесь на них, а не на частый опрос:

HTTP/1.1 429 Too Many Requests
Retry-After: 37
X-RateLimit-Limit: 30
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1694007937

`internal_error`

HTTP 500. Неожиданный сбой на нашей стороне. Ретраить тот же запрос безопасно после короткого бэкоффа — с Idempotency-Key ретрай не создаст дубликат. Если сохраняется, проверьте GET /v1/ping и напишите в поддержку.