Как различать ошибки внешнего сервиса и ошибки собственной интеграции?

Для устойчивой системы критично понимать, кто именно виноват в ошибке — вы или внешняя зависимость.

Определение

Ошибка внешнего сервиса — корректный или некорректный ответ зависимости, возникший вне вашего контроля.
Ошибка интеграции — ошибка, вызванная неправильным использованием API или логикой вашего сервиса.

Признаки ошибок внешнего сервиса

1. Сетевые проблемы

   • timeout

   • connection reset

   • DNS errors

2. HTTP 5xx

   • сервис недоступен

   • внутренняя ошибка провайдера

3. Нестабильность во времени

   • одинаковые запросы иногда успешны, иногда нет

Признаки ошибок собственной интеграции

1. HTTP 4xx

   • некорректные параметры

   • неверный формат запроса

2. Ошибки десериализации

   • неожиданный JSON

   • отсутствующие поля

3. Логические ошибки

   • неверная интерпретация статусов

   • нарушение контракта API

Практический подход

Перед началом списка важно отметить: одна и та же ошибка может выглядеть по-разному без контекста.

1. Логировать запрос и ответ

   • URL, параметры, headers (без чувствительных данных)

2. Разделять типы исключений

   • transport / protocol / business

3. Вводить собственную классификацию ошибок

   • ExternalServiceError

   • IntegrationError

4. Сравнивать с документацией API

Мини-пример классификации

if response.status_code >= 500:
    raise ExternalServiceError()
elif response.status_code == 400:
    raise IntegrationError()

Вывод

Чёткое различие между ошибками внешнего сервиса и ошибками интеграции позволяет быстрее устранять проблемы, корректно настраивать ретраи и не искажать метрики стабильности.