使用gspread访问Google Spreadsheet的读请求报500错误如何解决

算力阿峰

2026-10-7

错误触发原因

该500错误属于Google Sheets API服务端返回的内部错误，并非代码语法逻辑问题，此前运行正常无修改的情况下，常见触发原因如下：

Google Sheets API服务临时波动、区域故障
服务账号权限被变更：表格所有者移除了服务账号的共享权限、权限等级被下调，或者表格被移动/删除/设置为私有
API请求配额超限：短时间内请求频次过高，触发谷歌API限流规则，返回500错误
原表格存在异常内容：表格包含大量复杂公式、嵌入对象、损坏的单元格格式，导致API拉取元数据时服务端处理失败
依赖库版本兼容问题：gspread或认证依赖库的旧版本与谷歌最新API接口规范不兼容

排查修复步骤

验证基础权限：手动打开你使用的表格URL，确认表格未被删除、移动，个人账号可正常访问；再检查表格共享列表，确认credentials.json文件中client_email字段对应的服务账号邮箱仍在共享列表中，且至少有查看者权限，写入操作需要编辑者权限。
添加重试逻辑规避临时波动：500错误多数为偶发临时故障，可添加重试逻辑解决，参考代码如下：

import time
import pandas as pd
import gspread
from oauth2client.service_account import ServiceAccountCredentials

CREDENTIALS_JSON = 'credentials.json'
SCOPES = ['https://spreadsheets.google.com/feeds','https://www.googleapis.com/auth/drive']
creds = ServiceAccountCredentials.from_json_keyfile_name(CREDENTIALS_JSON, SCOPES)
client = gspread.authorize(creds)

gc = client.open_by_url('<你的表格URL>')

max_retries = 5
retry_count = 0
worksheets = None
# 重试获取工作表列表
while retry_count < max_retries:
    try:
        worksheets = gc.worksheets()
        sheet1 = gc.get_worksheet_by_id(<你的工作表ID>)
        break
    except gspread.exceptions.APIError as e:
        if e.response.status_code == 500:
            retry_count += 1
            time.sleep(3)
        else:
            raise e
if not worksheets:
    raise Exception("多次重试后仍无法访问表格")

验证配额使用情况：进入谷歌云控制台对应项目的Google Sheets API管理页，查看配额使用情况，确认未超过每秒请求数、每日请求数上限，超限可等待配额重置或申请提升配额。
排查表格本身问题：改用client.open_by_key('<表格ID>')（表格ID为URL中d/和下一个/之间的字符串）替代open_by_url避免解析问题；新建空白测试表格给服务账号授权后调用相同接口，如果空白表格访问正常，说明原表格存在格式异常，可导出原表格内容重新导入新建副本，再更新代码中的表格地址即可。
升级依赖库：执行命令pip install --upgrade gspread oauth2client升级相关依赖，避免旧版本和谷歌最新API不兼容。

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