Ошибки
Формат ошибок и коды.
Любая ошибка возвращается с HTTP-статусом 4xx/5xx и телом:
{
"success": false,
"error": {
"code": -1007,
"type": "validation",
"message": "Проверьте поля запроса",
"details": [{ "field": "quantity", "message": "Минимум 50" }]
},
"meta": { "requestId": "8e3c…", "timestamp": "2026-09-26T10:15:30.000Z", "processingTimeMs": 3 }
}codeэто стабильный числовой код, на него и опирайтесь в коде;messageможет меняться и переводится поAccept-Language.details: ошибки по полям (только для валидации).data: дополнительные данные ошибки, если есть.meta.requestIdсовпадает с заголовкомx-request-id, укажите его, когда пишете в поддержку.
HTTP-статусы
| Статус | Когда | Что делать |
|---|---|---|
400 | ошибка валидации (-1007), нет Idempotency-Key (-11001), некорректный username (-9202), товар (-9203) или externalId (-9204) | исправить запрос |
401 | нет ключа, ключ неверный или отозван | проверить X-API-Key |
402 | не хватает баланса (-9301) | пополнить баланс |
403 | IP не в allowlist Project | добавить адрес сервера |
404 | заказ не найден или принадлежит другому Project (-9201) | проверить id заказа |
409 | запрос с этим Idempotency-Key ещё выполняется (-11003); externalId уже занят заказом с другими параметрами (-9207) | повторить позже или проверить заказ |
422 | получатель не найден (-9002), получателю нельзя подарить (-9003), Idempotency-Key использован с другим телом (-11002) | показать ошибку покупателю или взять новый ключ; не повторять как есть |
429 | превышен лимит (-11005) | повторить после Retry-After |
502 | поставщик временно недоступен (-9006) | повторить через несколько секунд |
5xx | ошибка на нашей стороне | повторить с тем же Idempotency-Key |
Диапазоны кодов
| Коды | Область |
|---|---|
-1000…-1999 | общие (валидация, доступ) |
-11001…-11099 | идемпотентность и лимиты |
-9001…-9099 | поставщик (получатель не найден, недоступен) |
-9201…-9299 | заказы |
-9301…-9399 | цены и баланс |
-9101…-9199 | Supplier Accounts |
-9401…-9499 | вебхуки |
Полный список кодов для каждого метода есть в справочнике API.