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

Question

Ошибки внешнего сервиса обычно проявляются как сетевые сбои, таймауты или корректные HTTP-ответы с кодами 4xx/5xx. Ошибки интеграции возникают из-за неправильных запросов, форматов данных, логики обработки или ожиданий от API. Для различения важно анализировать тип ошибки, код ответа и контекст запроса. Также помогают логи запросов и ответов. Чёткое разделение ошибок упрощает отладку и поддержку.

YeaHub · Accepted Answer

Для устойчивой системы критично понимать, кто именно виноват в ошибке — вы или внешняя зависимость.ОпределениеОшибка внешнего сервиса — корректный или некорректный ответ зависимости, возникший вне вашего контроля.Ошибка интеграции — ошибка, вызванная неправильным использованием API или логикой вашего сервиса.Признаки ошибок внешнего сервисаСетевые проблемыtimeoutconnection resetDNS errorsHTTP 5xxсервис недоступенвнутренняя ошибка провайдераНестабильность во времениодинаковые запросы иногда успешны, иногда нетПризнаки ошибок собственной интеграцииHTTP 4xxнекорректные параметрыневерный формат запросаОшибки десериализациинеожиданный JSONотсутствующие поляЛогические ошибкиневерная интерпретация статусовнарушение контракта APIПрактический подходПеред началом списка важно отметить: одна и та же ошибка может выглядеть по-разному без контекста.Логировать запрос и ответURL, параметры, headers (без чувствительных данных)Разделять типы исключенийtransport / protocol / businessВводить собственную классификацию ошибокExternalServiceErrorIntegrationErrorСравнивать с документацией APIМини-пример классификацииif response.status_code >= 500:
    raise ExternalServiceError()
elif response.status_code == 400:
    raise IntegrationError()
ВыводЧёткое различие между ошибками внешнего сервиса и ошибками интеграции позволяет быстрее устранять проблемы, корректно настраивать ретраи и не искажать метрики стабильности.