Помилки й відновлення

За стабільним кодом помилки визначайте, чи потрібно виправити запит, зачекати або повторити його.

Що робити

Вибирайте дію за статусом HTTP та error.code, а не за текстом error.message.
Статус 401 потребує правильної автентифікації; 403 — зміни доступу чи тарифу; 409 — перевірки конфліктної операції або версії ресурсу.

Відмова в доступі та повторні спроби

401: 401 не завжди означає завершення дії токена. Якщо строк минув, отримайте новий токен і повторіть читання щонайбільше один раз. Якщо отримання токена повертає 401, перевірте ключ і зупиніть автоматичні спроби.
403: У разі 403 перевірте дозволи, обмеження IP і тариф. Новий токен не відновлює скасований доступ.

Автентифікація

Правила повторення

Для тимчасових збоїв обмежуйте кількість повторів, збільшуйте затримку та додавайте випадкове відхилення.
Дотримуйтеся Retry-After, якщо він наданий.
Після тайм-ауту запису його результат може бути невідомим: повторюючи ту саму логічну операцію, зберігайте початковий Idempotency-Key і незмінний запит.
Нижче пояснено кожен опублікований код помилки.

Безпечний запис

Обмеження частоти запитів

422 / 409

Для цін неправильний формат валюти або точність суми повертають 422 request.validation_failed.
Коректний код валюти, який не відповідає вибраному прайс-листу, повертає 409 resource.version_conflict.
Перед повторною спробою перевірте контекст і версії.

Каталог помилок

400request.malformedНеможливо розібрати запит.

Що робити: Перевірте синтаксис JSON, кодування URL і структуру запиту.
Правила повторення: Повторіть після виправлення запиту.

JSON

{
  "error": {
    "code": "request.malformed",
    "fields": null,
    "message": "The request could not be read."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.invalid_credentialsAPI-ключ або токен доступу недійсний, прострочений чи відкликаний.

Що робити: Перевірте URL магазину та облікові дані. Отримайте новий токен за допомогою активного API-ключа.
Правила повторення: Повторіть запит після виправлення автентифікації; уникайте багаторазових запитів із недійсним токеном.

JSON

{
  "error": {
    "code": "authentication.invalid_credentials",
    "fields": null,
    "message": "The credentials are invalid."
  },
  "meta": {
    "request_id": "example-request"
  }
}

401authentication.requiredОбов’язковий заголовок Authorization відсутній або має неправильну схему.

Що робити: Для отримання токена використовуйте ApiKey, а для операцій із ресурсами — Bearer.
Правила повторення: Повторіть запит після додавання правильного заголовка.

JSON

{
  "error": {
    "code": "authentication.required",
    "fields": null,
    "message": "Authentication is required."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403authorization.client_ip_unverifiedСлужба не змогла достовірно визначити IP-адресу клієнта.

Що робити: Попросіть оператора магазину перевірити шлях вхідного з’єднання. Не додавайте заголовки пересилання самостійно.
Правила повторення: Повторіть запит після відновлення довіреного шляху з’єднання.

JSON

{
  "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 ключа.
Правила повторення: Повторюйте запит лише після дозволу цієї адреси.

JSON

{
  "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Ключ не має чинного дозволу, потрібного для цієї операції.

Що робити: Перевірте обов’язкові та умовні дозволи операції, дозволи ключа й доступ його видавця.
Правила повторення: Повторіть запит після того, як уповноважений адміністратор надасть потрібний доступ.

JSON

{
  "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 не буде ввімкнено.

JSON

{
  "error": {
    "code": "entitlements.api_disabled",
    "fields": null,
    "message": "API access is disabled for this store."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.limit_exceededЗміна перевищила б ліміт поточного тарифу.

Що робити: Перевірте відповідний ліміт ресурсу й скоригуйте заплановану зміну або тариф.
Правила повторення: Повторіть після усунення обмеження; якщо запит змінюється, використайте новий ключ ідемпотентності.

JSON

{
  "error": {
    "code": "entitlements.limit_exceeded",
    "fields": null,
    "message": "The operation exceeds a plan limit."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.operation_disabledПоточний тариф не включає цю операцію.

Що робити: Перевірте мінімальний тариф, указаний для операції.
Правила повторення: Повторіть запит, коли тариф дозволятиме операцію, а ключ матиме потрібні дозволи.

JSON

{
  "error": {
    "code": "entitlements.operation_disabled",
    "fields": null,
    "message": "The current plan does not allow this operation."
  },
  "meta": {
    "request_id": "example-request"
  }
}

403entitlements.resource_blockedЛіміт тарифу блокує цей конкретний ресурс.

Що робити: Попросіть власника усунути тарифне обмеження ресурсу.
Правила повторення: Не повторюйте той самий запит, доки ресурс залишається заблокованим.

JSON

{
  "error": {
    "code": "entitlements.resource_blocked",
    "fields": null,
    "message": "A plan limit blocks access to this resource."
  },
  "meta": {
    "request_id": "example-request"
  }
}

404resource.not_foundРесурс відсутній, видалений або недоступний за переданим ідентифікатором.

Що робити: Перевірте магазин, шлях ресурсу та ідентифікатор. Використовуйте ідентифікатори, повернуті цим магазином.
Правила повторення: Повторюйте лише після виправлення цілі або підтвердження її існування.

JSON

{
  "error": {
    "code": "resource.not_found",
    "fields": null,
    "message": "The resource was not found."
  },
  "meta": {
    "request_id": "example-request"
  }
}

405request.method_not_allowedКінцева точка не підтримує цей метод HTTP.

Що робити: Використовуйте задокументований метод; заголовок Allow указує підтримувані методи.
Правила повторення: Не повторюйте запит із непідтримуваним методом.

JSON

{
  "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Цей ключ ідемпотентності належить іншому запиту.

Що робити: Знайдіть початкову операцію. Використовуйте новий ключ лише для навмисно нової логічної операції.
Правила повторення: Не повторюйте запит зі зміненими даними та конфліктним ключем.

JSON

{
  "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Унікальне значення конфліктує з наявним ресурсом.

Що робити: Прочитайте наявний ресурс і вирішіть, чи використати його, чи вибрати інше унікальне значення.
Правила повторення: Не повторюйте те саме конфліктне створення.

JSON

{
  "error": {
    "code": "resource.already_exists",
    "fields": null,
    "message": "A resource with these unique values already exists."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.in_useІнші ресурси досі залежать від цього ресурсу.

Що робити: Перевірте залежності та перед видаленням усуньте або змініть їх через підтримувані операції.
Правила повторення: Повторіть після усунення залежностей.

JSON

{
  "error": {
    "code": "resource.in_use",
    "fields": null,
    "message": "The resource is still in use."
  },
  "meta": {
    "request_id": "example-request"
  }
}

409resource.state_conflictПоточний бізнес-стан не дозволяє цю зміну.

Що робити: Прочитайте поточний стан і виберіть допустимий бізнес-перехід.
Правила повторення: Не застосовуйте конфліктну зміну примусово й не надсилайте її повторно автоматично.

JSON

{
  "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.
Правила повторення: Для переглянутої операції використовуйте новий ключ ідемпотентності; не перезаписуйте дані без перевірки.

JSON

{
  "error": {
    "code": "resource.version_conflict",
    "fields": null,
    "message": "The resource version has changed."
  },
  "meta": {
    "request_id": "example-request"
  }
}

413request.too_largeЗапит перевищує обмеження розміру.

Що робити: Зменште обсяг даних або розділіть завдання на підтримувані окремі операції.
Правила повторення: Повторіть менші коректні операції з власними ключами ідемпотентності.

JSON

{
  "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 і підтримуване нестиснене тіло запиту.
Правила повторення: Повторіть запит після виправлення типу даних або кодування.

JSON

{
  "error": {
    "code": "request.unsupported_media_type",
    "fields": null,
    "message": "The request media type or encoding is not supported."
  },
  "meta": {
    "request_id": "example-request"
  }
}

422request.validation_failedОдне чи кілька полів або параметрів не пройшли перевірку.

Що робити: Перегляньте error.fields, а потім перевірте обов’язкові поля, допустимість null, ідентифікатори й дозволені значення.
Правила повторення: Повторіть виправлений запит; змінений запис є новою логічною операцією.

JSON

{
  "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 секунд і додайте випадкову затримку. Повторюючи запис, зберігайте початковий ключ і дані.

JSON

{
  "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 секунд і додайте випадкову затримку. Повторюючи запис, зберігайте початковий ключ і дані.

JSON

{
  "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 секунд і додайте випадкову затримку. Повторюючи запис, зберігайте початковий ключ і дані.

JSON

{
  "error": {
    "code": "rate_limit.exceeded",
    "fields": null,
    "message": "The request rate limit has been exceeded."
  },
  "meta": {
    "request_id": "example-request"
  }
}

500internal.errorВиникла неочікувана помилка служби.

Що робити: Запишіть ідентифікатор запиту й зверніться до оператора, якщо помилка повторюється; не записуйте облікові дані до журналів.
Правила повторення: Обмежуйте кількість повторів і збільшуйте затримку. Для запису зберігайте початковий ключ ідемпотентності та незмінні дані.

JSON

{
  "error": {
    "code": "internal.error",
    "fields": null,
    "message": "An unexpected error occurred."
  },
  "meta": {
    "request_id": "example-request"
  }
}

502gateway.bad_responseШлюз не отримав коректної відповіді API.

Що робити: Збережіть ідентифікатор запиту. Невдала відповідь не доводить, що запис не було застосовано.
Правила повторення: Обмежуйте кількість повторів і збільшуйте затримку; ту саму логічну операцію запису повторюйте з початковим Idempotency-Key та незмінними даними.

JSON

{
  "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, якщо він наданий, і зберігайте ідентифікатор запиту, якщо збій триває.
Правила повторення: Обмежуйте кількість повторів, збільшуйте затримку та додавайте випадкове відхилення; повторюючи той самий запис, зберігайте ключ і дані.

JSON

{
  "error": {
    "code": "service.unavailable",
    "fields": null,
    "message": "The API is temporarily unavailable."
  },
  "meta": {
    "request_id": "example-request"
  }
}

504gateway.timeoutШлюз перевищив час очікування відповіді API.

Що робити: Збережіть ідентифікатор запиту й вважайте результат запису невідомим.
Правила повторення: Обмежуйте кількість повторів і збільшуйте затримку; для запису зберігайте початковий ключ ідемпотентності та незмінні дані.

JSON

{
  "error": {
    "code": "gateway.timeout",
    "fields": null,
    "message": "The API gateway timed out."
  },
  "meta": {
    "request_id": "example-request"
  }
}