Ветвитесь по стабильным codes, не по сообщениям

Ошибки возвращаются как application/problem+json с HTTP status и machine-readable code. Преобразуйте их в собственную типизированную модель на data-access boundary. Читаемые детали предназначены для безопасной диагностики и могут уточняться; они не должны управлять логикой или показывать пользователю инфраструктурные исключения.

Считайте 401 ошибкой конфигурации или отзывом

authentication_required означает, что X-API-Key отсутствует, неверен или отозван. Повтор с тем же ключом проблему не исправит. Остановите операцию, предупредите владельца интеграции и проверьте deployment secrets. Не переключайтесь на ключ другого клиента и не отдавайте upstream response напрямую браузеру.

HTTP 402 — граница бюджета

insufficient_credits детерминирован и содержит cost и remaining. Приостановите scheduler, при необходимости покажите безопасный cached state и направьте billing owner в developer dashboard. Tight retry loop создаёт только новые отклонённые вызовы и скрывает необходимое коммерческое действие.

Повторяйте только ограниченные безопасные операции

Уважайте Retry-After на 429 и используйте exponential backoff с jitter для временных 502 provider failures. GET и идемпотентное provisioning подходят для retry. Не повторяйте connect mutation после неизвестного результата вслепую: сначала запросите список аккаунтов и проверьте, был ли ресурс создан.

Передавайте correlation ID через всю границу

Отправляйте валидированный X-Correlation-ID и логируйте его с portfolioId, операцией и latency. Это связывает диагностику продукта и API без секретов. Возвращайте безопасный support reference, а не provider payload, database details или stack trace.