DRF Token认证返回非JSON HTTP 500错误的解决方法

• 观测到的500原生HTML响应，本质是DRF的异常捕获流程未正确匹配抛出的认证异常，最终将异常抛给Django全局错误处理流程的结果。哪怕handle_exception方法中存在对AuthenticationFailed的分支判断，只要实际抛出的异常不符合判断范围，就会直接跳过该分支，触发未捕获异常逻辑。
• 常见的触发场景：
  • 异常抛出位置不在DRF视图的调度链路内：比如全局中间件、路由装饰器、第三方认证插件的非DRF兼容逻辑抛出的异常，根本不会进入DRF的异常捕获流程，会直接被Django全局处理。
  • 异常类型不匹配：代码中导入的AuthenticationFailed是Django原生的django.core.exceptions.AuthenticationFailed，而非DRF体系内的rest_framework.exceptions.AuthenticationFailed。注意：两个类无继承关系，哪怕类名完全一致，isinstance判断也不会匹配成功，最终会跳过预设的异常分支。
  • 全局异常处理器配置失效：默认的DRF异常处理器仅能识别DRF体系内的异常，当遇到非体系内的认证异常时会返回None，触发未捕获异常流程。

1. 实现统一兼容的全局异常处理器 #

• 在项目公共工具模块下编写自定义异常处理逻辑，优先承接DRF默认异常处理，再对非DRF体系的认证、权限类异常做兼容，统一返回前后端约定的JSON格式：

  from rest_framework.views import exception_handler
  from rest_framework.response import Response
  from rest_framework import status
  from django.core.exceptions import (
      AuthenticationFailed as DjangoAuthFailed,
      PermissionDenied as DjangoPermissionDenied
  )
  
  def unified_exception_handler(exc, context):
      # 优先调用DRF默认异常处理器，处理所有可识别的DRF体系异常
      response = exception_handler(exc, context)
      # 兼容非DRF体系抛出的认证、权限类异常
      if response is None:
          if isinstance(exc, (DjangoAuthFailed, DjangoPermissionDenied)):
              return Response(
                  {"detail": "身份校验失败，请重新登录"},
                  status=status.HTTP_401_UNAUTHORIZED
              )
      return response
  

• 在settings.py的REST_FRAMEWORK配置项中指向该自定义处理器：

  REST_FRAMEWORK = {
      # 保留原有全局配置
      "EXCEPTION_HANDLER": "your_project.utils.unified_exception_handler"
  }
  

2. 排查实际异常的类型来源 #

• 临时在自定义异常处理器中打印实际异常的类路径，定位不匹配的根因：

  def unified_exception_handler(exc, context):
      print(f"未捕获异常类型：{type(exc)}")
      # 原有处理逻辑
  

• 所有手动抛出的认证、权限类异常统一替换为DRF体系的异常类，避免导入Django原生的同名异常导致匹配失效。

3. 校验认证链路配置 #

• 检查DEFAULT_AUTHENTICATION_CLASSES的配置顺序，将Token认证类放在靠前位置，避免其他认证类提前抛出非兼容的异常。
• 排查全局中间件、第三方插件的token校验逻辑，若存在提前拦截请求的逻辑，需将其抛出的异常替换为可被异常处理器识别的类型，避免异常在进入DRF视图调度流程前就被抛给Django全局处理。

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