Перейти до вмісту
ShopentlyLearn

Коди помилок

Якщо запит не вдався, перевірте код помилки у відповіді. Розгорніть його в списку нижче, щоб дізнатися, що сталося та що робити далі. Для кожної помилки є приклад відповіді та поради щодо повторного запиту.

400request.malformedНеможливо розібрати запит.
Що робити
Перевірте синтаксис JSON, кодування URL і структуру запиту.
Правила повторення
Повторіть після виправлення запиту.
Відповідь
{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI-ключ або токен доступу недійсний, прострочений чи відкликаний.
Що робити
Перевірте URL магазину та облікові дані. Отримайте новий токен за допомогою активного API-ключа.
Правила повторення
Повторіть запит після виправлення автентифікації; уникайте багаторазових запитів із недійсним токеном.
Відповідь
{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredОбов’язковий заголовок Authorization відсутній або має неправильну схему.
Що робити
Для видачі або скасування токену використовуйте ключ API з ApiKey у заголовку Authorization. Для інших запитів використовуйте токен доступу з Bearer.
Правила повторення
Повторіть запит після додавання правильного заголовка.
Відповідь
{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedСлужба не змогла достовірно визначити IP-адресу клієнта.
Що робити
Перевірте, з якої IP-адреси інтеграція підключається до API. Якщо помилка повторюється, зверніться до технічної підтримки Shopently.
Правила повторення
Спробуйте ще раз після усунення проблеми з визначенням IP-адреси.
Відповідь
{
  "error": {
    "code": "authorization.client_ip_unverified",
    "fields": null,
    "message": "The client IP address could not be verified."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.ip_not_allowedIP-адреса джерела не входить до списку дозволених адрес ключа.
Що робити
Використовуйте дозволену адресу джерела або попросіть уповноваженого адміністратора змінити список IP ключа.
Правила повторення
Повторюйте запит лише після дозволу цієї адреси.
Відповідь
{
  "error": {
    "code": "authorization.ip_not_allowed",
    "fields": null,
    "message": "Access from this IP address is not allowed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.scope_deniedКлюч не має чинного дозволу, потрібного для цієї операції.
Що робити
Перевірте обов’язкові та умовні дозволи операції, дозволи ключа й доступ його видавця.
Правила повторення
Повторіть запит після того, як уповноважений адміністратор надасть потрібний доступ.
Відповідь
{
  "error": {
    "code": "authorization.scope_denied",
    "fields": null,
    "message": "The required permission has not been granted."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.api_disabledДоступ до API для цього магазину вимкнено.
Що робити
Попросіть власника магазину перевірити активний тариф і доступність API.
Правила повторення
Не повторюйте запит, доки доступ до API не буде ввімкнено.
Відповідь
{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededЗміна перевищила б ліміт поточного тарифу.
Що робити
Перевірте відповідний ліміт ресурсу й скоригуйте заплановану зміну або тариф.
Правила повторення
Повторіть після усунення обмеження; якщо запит змінюється, використайте новий ключ ідемпотентності.
Відповідь
{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledПоточний тариф не включає цю операцію.
Що робити
Перевірте мінімальний тариф, указаний для операції.
Правила повторення
Повторіть запит, коли тариф дозволятиме операцію, а ключ матиме потрібні дозволи.
Відповідь
{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedЛіміт тарифу блокує цей конкретний ресурс.
Що робити
Попросіть власника усунути тарифне обмеження ресурсу.
Правила повторення
Не повторюйте той самий запит, доки ресурс залишається заблокованим.
Відповідь
{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundРесурс відсутній, видалений або недоступний за переданим ідентифікатором.
Що робити
Перевірте магазин, шлях ресурсу та ідентифікатор. Використовуйте ідентифікатори, повернуті цим магазином.
Правила повторення
Повторюйте лише після виправлення цілі або підтвердження її існування.
Відповідь
{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedКінцева точка не підтримує цей метод HTTP.
Що робити
Використовуйте задокументований метод; заголовок Allow указує підтримувані методи.
Правила повторення
Не повторюйте запит із непідтримуваним методом.
Відповідь
{
  "error": {
    "code": "request.method_not_allowed",
    "fields": null,
    "message": "This method is not supported for this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409idempotency.key_reusedЦей ключ ідемпотентності належить іншому запиту.
Що робити
Знайдіть початкову операцію. Використовуйте новий ключ лише для навмисно нової логічної операції.
Правила повторення
Не повторюйте запит зі зміненими даними та конфліктним ключем.
Відповідь
{
  "error": {
    "code": "idempotency.key_reused",
    "fields": null,
    "message": "This idempotency key was used with a different request."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.already_existsУнікальне значення конфліктує з наявним ресурсом.
Що робити
Прочитайте наявний ресурс і вирішіть, чи використати його, чи вибрати інше унікальне значення.
Правила повторення
Не повторюйте те саме конфліктне створення.
Відповідь
{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useІнші ресурси досі залежать від цього ресурсу.
Що робити
Перевірте залежності та перед видаленням усуньте або змініть їх через підтримувані операції.
Правила повторення
Повторіть після усунення залежностей.
Відповідь
{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictПоточний бізнес-стан не дозволяє цю зміну.
Що робити
Прочитайте поточний стан і виберіть допустимий бізнес-перехід.
Правила повторення
Не застосовуйте конфліктну зміну примусово й не надсилайте її повторно автоматично.
Відповідь
{
  "error": {
    "code": "resource.state_conflict",
    "fields": null,
    "message": "The current resource state does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.version_conflictІнший запис змінив ресурс після прочитаної вами версії.
Що робити
Прочитайте найновіший стан, узгодьте свою зміну й передайте нове expected_version.
Правила повторення
Для переглянутої операції використовуйте новий ключ ідемпотентності; не перезаписуйте дані без перевірки.
Відповідь
{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409storage.limit_reachedВичерпано місце для зображень і файлів. Звільніть місце або збільште ліміт.
Що робити
Вичерпано місце для зображень і файлів. Звільніть місце або збільште ліміт.
Правила повторення
Повторіть менші коректні операції з власними ключами ідемпотентності.
Відповідь
{
  "error": {
    "code": "storage.limit_reached",
    "fields": null,
    "message": "The upload storage limit is reached."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeЗапит перевищує обмеження розміру.
Що робити
Зменште обсяг даних або розділіть завдання на підтримувані окремі операції.
Правила повторення
Повторіть менші коректні операції з власними ключами ідемпотентності.
Відповідь
{
  "error": {
    "code": "request.too_large",
    "fields": null,
    "message": "The request exceeds the size limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

415request.unsupported_media_typeТип даних або кодування вмісту не підтримується.
Що робити
Для запису JSON використовуйте Content-Type: application/json і підтримуване нестиснене тіло запиту.
Правила повторення
Повторіть запит після виправлення типу даних або кодування.
Відповідь
{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

416request.range_not_satisfiableОбмеження: Range
Що робити
Range: bytes=0-(size_bytes-1)
Правила повторення
Повторіть після виправлення запиту.
Відповідь
{
  "error": {
    "code": "request.range_not_satisfiable",
    "fields": null,
    "message": "The requested byte range is unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedОдне чи кілька полів або параметрів не пройшли перевірку.
Що робити
Перегляньте error.fields, а потім перевірте обов’язкові поля, допустимість null, ідентифікатори й дозволені значення.
Правила повторення
Повторіть виправлений запит; змінений запис є новою логічною операцією.
Відповідь
{
  "error": {
    "code": "request.validation_failed",
    "fields": null,
    "message": "Some request parameters are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.queue_fullКоротка черга API заповнена; виконання запиту не розпочалося.
Що робити
Ставте запити в чергу та дотримуйтеся заголовка відповіді Retry-After.
Правила повторення
Зачекайте щонайменше кількість секунд, указану в Retry-After. Якщо повторюєте запис, збережіть те саме тіло запиту та значення Idempotency-Key.
Відповідь
{
  "error": {
    "code": "capacity.queue_full",
    "fields": null,
    "message": "The API is busy. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429capacity.wait_timeoutЧас очікування в черзі API минув; виконання запиту не розпочалося.
Що робити
Ставте запити в чергу та дотримуйтеся заголовка відповіді Retry-After.
Правила повторення
Зачекайте щонайменше кількість секунд, указану в Retry-After. Якщо повторюєте запис, збережіть те саме тіло запиту та значення Idempotency-Key.
Відповідь
{
  "error": {
    "code": "capacity.wait_timeout",
    "fields": null,
    "message": "The API could not start this request in time. Please retry shortly."
  },
  "meta": {
    "request_id": "example-request"
  }
}

429rate_limit.exceededЧастота запитів перевищує чинне обмеження.
Що робити
Ставте запити в чергу та дотримуйтеся заголовка відповіді Retry-After.
Правила повторення
Зачекайте щонайменше кількість секунд, указану в Retry-After. Якщо повторюєте запис, збережіть те саме тіло запиту та значення Idempotency-Key.
Відповідь
{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorВиникла неочікувана помилка служби.
Що робити
Трохи зачекайте перед повторним запитом. Якщо помилка 500 виникне знову, зверніться до технічної підтримки Shopently і вкажіть ідентифікатор запиту.
Правила повторення
Після короткої паузи можна повторити читання даних. Повторюючи запис, використовуйте те саме значення Idempotency-Key та не змінюйте тіло запиту.
Відповідь
{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseШлюз не отримав коректної відповіді API.
Що робити
Збережіть ідентифікатор запиту. Невдала відповідь не доводить, що запис не було застосовано.
Правила повторення
Обмежуйте кількість повторів і збільшуйте затримку; ту саму логічну операцію запису повторюйте з початковим Idempotency-Key та незмінними даними.
Відповідь
{
  "error": {
    "code": "gateway.bad_response",
    "fields": null,
    "message": "The API gateway could not obtain a valid response."
  },
  "meta": {
    "request_id": "example-request"
  }
}

503service.unavailableAPI тимчасово не може обробити запит.
Що робити
Якщо відповідь містить заголовок Retry-After, перед повторною спробою зачекайте вказану кількість секунд. Інакше зачекайте трохи. Якщо помилка повторюється, зверніться до технічної підтримки Shopently і вкажіть ідентифікатор запиту.
Правила повторення
Спробуйте ще раз після очікування, описаного вище. Повторюючи запис, використовуйте те саме значення Idempotency-Key та не змінюйте тіло запиту.
Відповідь
{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutШлюз перевищив час очікування відповіді API.
Що робити
Якщо запит змінював дані, перевірте, чи збереглися зміни в магазині. Відсутність відповіді не означає, що запис не відбувся. Якщо помилка повторюється, зверніться до технічної підтримки Shopently і вкажіть ідентифікатор запиту.
Правила повторення
Після короткої паузи можна повторити читання даних. Повторюючи запис, використовуйте те саме значення Idempotency-Key та не змінюйте тіло запиту.
Відповідь
{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}