Грешки и възстановяване

Използвайте устойчивите кодове за грешки, за да решите дали да коригирате, да изчакате или да повторите.

Какво да направите

Избирайте поведението според 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_allowedИзходният IP адрес не е в списъка с разрешени адреси за ключа.

Какво да направите: Използвайте одобрен изходен адрес или помолете упълномощен администратор да редактира 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_disabledAPI достъпът е изключен за този магазин.

Какво да направите: Помолете собственика да провери активния план и наличността на 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_allowedEndpoint не поддържа този 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"
  }
}