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