Разработчикам
Ошибки API
Каждый отказ приходит как application/problem+json с постоянным type. Ветвитесь по type, а не по тексту: здесь — что значит каждый и что делать.
Не нашли ответа или отказ повторяется? Напишите нам и назовите X-Request-Id из ответа — по нему мы найдём запрос. Написать нам
Статус 401
- api_token_expired
Срок токена API истёк
Срок действия токена прошёл.
- api_token_invalid
Токен API недействителен
У токена неверный формат, не сходится контрольная сумма или такого токена нет.
- api_token_missing
Нужен токен API
В запросе нет заголовка Authorization: Bearer. Токен в строке запроса не принимается.
- api_token_revoked
Токен API отозван
Токен отозван, приложение удалено, его служебный участник выключен или магазин закрыт.
Статус 403
- capability_disabled
Ресурс недоступен этому магазину
Ресурс держит возможность магазина, а у этого магазина её нет; capability — какая. Налоговые периоды, например, ведутся только у магазинов Аргентины.
- forbidden
Доступ запрещён
Правило доступа магазина отказало в действии сверх scopes, например на точке, с которой приложение не работает.
- insufficient_scope
Не хватает доступа
У приложения нет scope, который нужен методу; его называют required_scope и заголовок WWW-Authenticate. Метод, который принимает любой из нескольких scopes, перечисляет их в accepted_scopes — хватит любого.
- integration_api_not_in_plan
API для интеграций нет в тарифе
Тариф магазина не включает API для интеграций.
- ip_not_allowed
Адрес не разрешён
Приложение принимает запросы только с перечисленных IP-адресов, а этот пришёл с другого.
Статус 404
- not_found
Не найдено
Записи нет или она принадлежит другому магазину; неизвестный путь получает тот же ответ.
Статус 405
- method_not_allowed
Метод не разрешён
Путь существует, но этот HTTP-метод не принимает.
Статус 409
- address_book_full
Адресная книга покупателя полна
Адресная книга покупателя достигла потолка магазина; limit — потолок.
- bulk_operation_finished
Операция уже закончилась
Операция уже закончилась, отменить её нельзя; operation_status — её статус.
- bulk_operation_queue_full
Очередь операций приложения полна
У приложения уже столько незаконченных массовых операций, сколько разрешено; limit — потолок.
- bulk_operation_result_unavailable
Файла результата нет
Результат операции-файла появляется целиком только у completed, а эта операция ещё идёт, отказала или отменена; operation_status — её статус.
- consent_required
Нужно согласие на последствия
Запись изменит другие данные магазина: consent_kind называет вид последствия, consequences считает, что изменится, consent_token — отпечаток показанного.
- customer_contact_in_use
Контакт уже у покупателя магазина
Телефон или email нового покупателя уже принадлежит покупателю магазина; их называют field и existing_customer_id.
- draft_order_closed
Черновик заказа закрыт
Черновик оформлен или отменён и больше не правится и не оформляется; current даёт его статус и заказ.
- external_id_archived
Запись с этим внешним id в архиве
Внешний id принадлежит записи в архиве магазина; его называет external_id.
- external_id_in_use
Внешний id занят
Внешний id уже у другой живой записи этого приложения; его называет external_id.
- fiscal_document_annul_refused
Фактуру не аннулировать
Фактуру не аннулировать. code — причина: not_an_invoice — документ не фактура; not_issued — фактура не выпущена: отклонённую перевыпускают, ждущую выпуска гасит отмена заказа; provider_disabled — фискальный модуль магазина выключен; already_voided — фактура уже снята или её нота ждёт выпуска; nothing_to_void — продажа возвращена целиком, встречные ноты обнулили фактуру. current.status — статус документа, current.annulling_document_id — действующая аннулирующая нота у already_voided.
- fiscal_document_dismiss_refused
Документ не снять с контроля
Документ не снять с контроля. code — причина: not_awaiting_decision — документ не ждёт решения человека: снимают отклонённый налоговой или выпущенный под CAEA, информирование которого ARCA не принимает; already_resolved — документ уже снят. current.status — статус документа сейчас.
- fiscal_document_pdf_unavailable
У документа нет файла
У документа нет файла: он не выпущен или провайдер не сохранил ни файла, ни данных для него; current.status — статус документа.
- fiscal_document_reissue_refused
Документ не перевыпустить
Документ не перевыпустить. code — причина: not_reissuable — документ не в сбое и не отклонён: ждёт выпуска или выпущен; advance_applied — аванс брони зачтён в чек, фактура чека его уже документирует; nothing_to_issue — заказ возвращён целиком. current.status — статус документа сейчас.
- idempotency_key_in_use
Запрос с этим ключом ещё исполняется
Запрос с тем же Idempotency-Key ещё исполняется.
- in_use_conflict
Запись используется
Запись нельзя удалить: на неё ещё ссылаются другие данные магазина.
- invoice_issue_refused
Фактуру по заказу сейчас не выпустить
Фактуру по заказу сейчас не выпустить. code — причина: channel_not_first_party — документ выпускает канал продажи; entity_exempt — юрлицо заказа документов не выпускает; issued_externally — документ выпускает внешняя касса; provider_disabled — фискальный модуль магазина выключен; not_covered — продажа ещё не оплачена; advance_applied — аванс брони зачтён в чек, его документирует фактура чека; invoice_exists — фактура уже есть или ждёт выпуска; invoice_rejected — фактуру отклонила налоговая; nothing_to_issue — заказ возвращён целиком; bill_required — у стола несколько счетов, на счёт выпускают касса или панель. current.invoice_id — действующая фактура заказа у invoice_exists и invoice_rejected.
- money_transaction_locked
Движение не меняется руками
Движение журнала не правится и не удаляется руками: у него есть документ-источник (тогда меняются только статья, контрагент и описание), это служебная строка журнала (начальный остаток, курсовая разница, отражение магазина группы) или часть перевода. detail называет причину, current.origin — происхождение строки, current.transfer_id — перевод.
- order_cancel_refused
Заказ нельзя отменить
Заказ сейчас не отменить: статус не допускает, кредит-ноту не выписать, наличные возвращает только касса с открытой сменой, идёт оплаченная подписка.
- order_transition_refused
Заказ нельзя перевести в этот статус
Магазин не разрешает эту смену статуса заказа: правила переходов, самовывоз без курьера, доставка без курьера или неоплаченный остаток перед завершением. detail называет причину, current показывает статус сейчас.
- payment_not_confirmable
Платёж нельзя подтвердить
Платёж уже не ждёт денег или его закрывает провайдер, а не человек; current показывает его статус.
- plan_limit_reached
Достигнут лимит тарифа
Тариф магазина не позволяет больше записей этого вида; limit — потолок.
- purchase_order_refused
Заказ поставщику не принимает эту команду
Заказ поставщику не принимает команду в нынешнем состоянии: правится только черновик и размещённый заказ, удаляется только черновик, отменяется размещённый, закрывается принятый, а разместить можно только у активных поставщика и точки. detail называет причину, current.status — статус заказа сейчас.
- record_limit_reached
Достигнут потолок записей
Магазин достиг потолка записей этого вида; limit — потолок. От тарифа он не зависит.
- refund_not_confirmable
Возврат не ждёт подтверждения выплаты
У возврата нет ручной выплаты, ждущей подтверждения: деньги вернул провайдер, касса или баланс.
- refund_refused
Заказ нельзя вернуть
Состояние заказа не допускает возврат: отменён, денег не получено, наличные сданы в кассу, карта продажи потрачена или аванс держит бронь. detail называет причину.
- shipment_in_progress
Выпуск отправления уже идёт
Выпуск отправления по заказу уже ждёт очереди или идёт, либо отправление сейчас отменяют.
- shipment_label_unavailable
Наклейки отправления нет
У заказа нет отправления, перевозчик ещё не выдал наклейку или её файл недоступен.
- shipment_outcome_unknown
Исход прошлого выпуска неизвестен
Связь с перевозчиком оборвалась после прошлого запроса выпуска, и неизвестно, создано ли отправление.
- shipment_refused
Отправление сейчас не выпустить
Отправление сейчас не выпустить: у способа доставки заказа нет перевозчика с интеграцией, заказ не отгружается или ждёт оплаты счёта. code — причина (no_carrier, not_shippable, awaits_bill_payment), current — статус заказа сейчас.
- shipment_tracking_refused
Номер отслеживания вручную не записать
Номер отслеживания у заказа вручную не записать и не снять. code — причина: carrier_integrated — номер выдаёт перевозчик с интеграцией, отправление выпускают через POST /v1/orders/{order}/shipment; manual_tracking_unsupported — способ доставки заказа не везёт службой доставки; order_closed — заказ отменён или возвращён. current — статус заказа сейчас.
- stock_held_by_write_offs
Остаток удержан списаниями на подтверждении
Установка ниже забрала бы количество, удержанное списаниями на подтверждении в магазине.
- stock_on_hand_changed
Остаток изменился
Физический остаток не совпадает с expected_on_hand: он изменился после чтения. current.on_hand показывает остаток сейчас.
- supplier_bill_payment_locked
Оплату счёта не отменить напрямую
Оплату счёта поставщика не отменить напрямую: зачёт, ноту кредита, аванс по заказу и расход журнала снимает их документ, а удержание при оплате в закрытом налоговом периоде держит и саму оплату. detail называет причину, current.kind — вид оплаты.
- supplier_bill_refused
Счёт поставщика не принимает эту команду
Счёт поставщика не принимает команду в нынешнем состоянии: правится и удаляется только черновик, проведённый счёт не правится, аннулированный не проводится, а удалению черновика мешают проведённые к нему ноты. Одобряют только проведённый счёт, отзыв одобрения невозможен после первой оплаты, платят только проведённый и одобренный. detail называет причину, current.status — статус счёта сейчас.
- tax_withholding_certificate_unavailable
Сертификата по записи нет
Сертификат магазин выдаёт только по удержанию, сделанному им самим (direction practiced), от своего юрлица: удержанное у магазина подтверждает бумага агента. current.direction — направление записи, current.legal_entity_id — её юрлицо.
- unique_conflict
Повтор значения
Параллельный запрос занял уникальное значение, например адрес или артикул, между проверкой и записью.
- upload_offset_mismatch
Часть не с того места
Смещение части не равно тому, что загрузка уже приняла; received — верное смещение.
- webhook_endpoint_limit_reached
У приложения предельное число адресов вебхуков
У приложения уже столько адресов вебхуков, сколько разрешено; limit — потолок.
Статус 410
- cursor_expired
Курсор синхронизации устарел
Курсор синхронизации старше срока хранения удалений или выдан до восстановления базы магазина.
Статус 412
- precondition_failed
Запись изменилась
Версия в If-Match не текущая: запись изменили после чтения. Для If-None-Match: * — запись уже существует.
Статус 416
- range_not_satisfiable
Диапазон за концом результата
Диапазон начинается дальше записанного результата; Content-Range даёт его длину.
Статус 422
- idempotency_key_required
Нужен ключ идемпотентности
Метод выполняется только с заголовком Idempotency-Key: его дубль в налоговой не отменить.
- idempotency_key_reused
Ключ идемпотентности уже использован
Ключ уже ушёл с другим запросом: другим методом, путём или телом.
- invalid_idempotency_key
Ключ идемпотентности неверен
Заголовок Idempotency-Key не разобран: ключ — от 1 до 255 видимых символов ASCII, токеном или строкой в кавычках.
- last_variant_of_product
Последний вариант товара
Товар не может остаться без вариантов, поэтому его последний вариант нельзя отправить в архив.
- money_out_of_range
Сумма вне диапазона
Цена, количество или единица дают сумму, слишком большую для точного расчёта.
- validation_error
Неверный запрос
Поле или параметр неверны или неизвестны; errors перечисляет сообщения по полям.
Статус 428
- precondition_required
Нужен If-Match
Правке версионируемой записи нужен If-Match с её ETag; * версией не считается.
Статус 429
- too_many_requests
Слишком много запросов
Лимит исчерпан; policy называет корзину — app, store или rejected, — а Retry-After говорит, сколько ждать. rejected значит, что с вашего адреса слишком много запросов отклонено на входе: токена нет, он неверный, отозван или истёк, адрес не разрешён, в тарифе нет API.
Статус 500
- server_error
Ошибка сервера
Неожиданный сбой на нашей стороне. Запрос не завершился.
Статус 503
- carrier_unavailable
Перевозчик не отвечает
Перевозчик не ответил на запрос, который магазин делает к нему за вас (наклейка отправления у Mercado Envíos).
- store_frozen
Магазин заморожен
Магазин заморожен за неоплату подписки.
- transient_conflict
Временный конфликт
Параллельное изменение откатило запрос целиком; ничего не записано.
Статус зависит от запроса
- http_error
Ошибка HTTP
Ошибка HTTP без своего типа, например 503 на время обслуживания.