Ошибки и ограничения API

Единый формат

API планируется с единым объектом ошибки: машиночитаемый код, понятное сообщение, идентификатор запроса и дополнительные сведения о неверных полях.

Категории ответов

• Ошибки запроса — неверные параметры или структура данных.
• Ошибки авторизации — отсутствующий или отозванный ключ.
• Ошибки доступа — недостаточные области или права проекта.
• Ограничения частоты — превышение допустимого числа запросов.
• Временные ошибки сервиса — запрос можно повторить позднее.

Повторные попытки

Повторяйте только безопасные операции и используйте увеличивающуюся задержку. Учитывайте заголовки ответа с рекомендуемым временем ожидания, когда они появятся в контракте.

Идентификатор запроса

Сохраняйте идентификатор запроса в журналах интеграции. Он поможет поддержке сопоставить ошибку клиента с серверным событием.

curl --request GET \
  "$MARKETHOUSE_API_URL/v1/products?project_id=project_demo&limit=0" \
  --header "Authorization: Bearer $MARKETHOUSE_API_KEY"

{
  "error": {
    "code": "validation_error",
    "message": "Параметры запроса не прошли проверку",
    "details": [
      {
        "field": "limit",
        "message": "Значение должно быть от 1 до 100"
      }
    ],
    "request_id": "req_demo_01"
  }
}