PHP如何返回8012错误码触发Retrofit执行onFailure回调

Retrofit 默认仅将 HTTP 状态码为 2xx 范围的响应当作成功请求，走onResponse回调；所有 4xx、5xx 范围的状态码都会被判定为请求失败，进入onFailure回调。要实现8012错误码触发onFailure的效果，核心是在余额不足场景返回非2xx的HTTP状态码，而非直接打印字符串返回200响应，具体改造分两端实现：

PHP服务端改造 #

• 废弃原有直接echo "8012";的逻辑，所有响应统一返回JSON格式，在输出响应内容前先设置对应HTTP状态码。
• 余额不足场景推荐使用402 Payment Required状态码，语义完全匹配支付类余额不足的场景，避免误用5xx类服务端错误状态码。
• 设置完响应头和输出内容后必须加exit终止后续逻辑，避免输出多余内容导致客户端解析失败。

代码示例 #

余额不足分支替换为如下代码：

// 钱包余额小于100时执行
http_response_code(402);
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'error_code' => 8012,
    'message' => '钱包余额不足，无法开通会员'
]);
exit;

会员开通成功分支统一返回200状态码的JSON响应：

// 扣款完成、会员状态更新成功后执行
http_response_code(200);
header('Content-Type: application/json; charset=utf-8');
echo json_encode([
    'code' => 0,
    'message' => '会员开通成功'
]);
exit;

安卓端Retrofit适配 #

• 移除原有onResponse中判断响应体是否包含8012的逻辑，将业务错误判断全部迁移到onFailure回调中。
• onFailure需要区分两类异常：一类是网络连接失败、超时等本地网络异常；另一类是服务端返回4xx/5xx的HTTP业务错误，后者需要从错误响应体中解析错误码做对应提示。

核心处理逻辑示例 #

override fun onFailure(call: Call<ApiResponse>, t: Throwable) {
    when(t) {
        is HttpException -> {
            // 处理服务端返回的业务错误
            val errorJson = t.response()?.errorBody()?.string()
            val errorResp = Gson().fromJson(errorJson, ErrorResponse::class.java)
            when(errorResp.error_code) {
                8012 -> Toast.makeText(mContext, "余额不足，请充值后再开通会员", Toast.LENGTH_SHORT).show()
                else -> Toast.makeText(mContext, "开通失败，请稍后重试", Toast.LENGTH_SHORT).show()
            }
        }
        else -> {
            // 处理纯网络异常
            Toast.makeText(mContext, "网络连接异常，请检查网络后重试", Toast.LENGTH_SHORT).show()
        }
    }
}

注意事项 #

• 不要返回纯文本格式的响应，全接口统一JSON结构可以大幅降低多端解析的兼容成本。
• 状态码设置必须在任何内容输出前执行，否则会触发headers already sent的PHP报错，导致状态码设置失效。

内容的提问来源于stack exchange，提问作者Taha Sami