HKUDS/DeepTutor · error · HTTPException

Channel onboarding provider request failed ({type(exc).__nam

Error message

Channel onboarding provider request failed ({type(exc).__name__})

What it means

502 raised by start_partner_channel_onboarding as the catch-all for any non-ChannelOnboardingError exception raised by onboarding.start(). The original exception is logged (logger.exception) and chained; the client only sees the exception class name, marking it as an upstream provider/infrastructure failure rather than a caller error.

Source

Thrown at deeptutor/api/routers/partners.py:847


def _onboarding_manager_and_partner(partner_id: str):
    mgr = get_partner_manager()
    if not mgr.partner_exists(partner_id):
        raise HTTPException(status_code=404, detail=t("api.partner_not_found"))
    return get_channel_onboarding_manager(), mgr


@router.post("/{partner_id}/channel-onboarding/start", dependencies=_MANAGEABLE)
async def start_partner_channel_onboarding(partner_id: str, payload: ChannelOnboardingStartRequest):
    onboarding, _ = _onboarding_manager_and_partner(partner_id)
    try:
        return await onboarding.start(partner_id, payload.channel)
    except ChannelOnboardingError as exc:
        raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None
    except Exception as exc:
        logger.exception("Failed to start channel onboarding for '%s'", partner_id)
        raise HTTPException(
            status_code=502,
            detail=f"Channel onboarding provider request failed ({type(exc).__name__})",
        ) from exc


@router.get("/{partner_id}/channel-onboarding/{session_id}", dependencies=_MANAGEABLE)
async def get_partner_channel_onboarding(partner_id: str, session_id: str):
    onboarding, _ = _onboarding_manager_and_partner(partner_id)
    try:
        return await onboarding.status(partner_id, session_id)
    except ChannelOnboardingError as exc:
        raise HTTPException(status_code=exc.status_code, detail=str(exc)) from None
    except Exception as exc:
        logger.exception("Failed to poll channel onboarding for '%s'", partner_id)
        raise HTTPException(
            status_code=502,
            detail=f"Channel onboarding provider request failed ({type(exc).__name__})",
        ) from exc

View on GitHub (pinned to 3e82f13042)

Solutions

Inspect server logs for the full traceback of the named exception type
Verify network reachability and credentials for the channel onboarding provider endpoint
Retry after fixing connectivity; report the exception type if it persists (likely a bug)

Defensive patterns

Strategy: retry

Try / catch

except HTTPStatusError as e:
    if e.response.status_code == 502:
        await asyncio.sleep(2 ** attempt)
        retry_start_onboarding()

Prevention

Verify provider endpoint reachability from the server host
Alert on repeated 502s — check logs for the chained traceback

When it happens

Trigger: Network-level failure reaching the channel onboarding provider (DNS, TLS, timeout), unexpected bug inside the onboarding manager, or serialization error of the provider response.

Common situations: Channel provider endpoint misconfigured or unreachable from the server; proxy/firewall blocking outbound calls; provider returned an unexpected response shape after an API change.

Related errors

AI-assisted analysis of HKUDS/DeepTutor@3e82f13042 (2026-08-27). Data as JSON: /api/errors/a15422eb327bfe66. Report an issue: GitHub.