直接开始吧这篇内容是给要跟 Gemini API 打交道的人看的。如果你只会用现成的 SDK或者每次调试都是复制粘贴别人的代码那这篇文章就是为你准备的。我用 curl 把 Gemini API 从请求到响应、从参数到错误码完整走了一遍整理成一份能直接照着排查问题的手册省得你再对着文档和报错来回折腾。1. 上手前的准备工作端点、密钥和第一个请求调试任何 API第一步都不是写代码而是把“你要打给谁、用什么身份、预期的响应长什么样”这三件事先确认清楚。Gemini API 的调试尤其如此因为它的鉴权方式、模型命名和参数格式跟大多数常见服务不太一样稍不留神就会在不起眼的地方卡住。1.1 API 密钥与鉴权方式两种传法都要会Gemini API 的密钥是一个字符串形如AIzaSy...。拿到密钥后在调用时有两个合法的携带位置放在 URL 的key查询参数里https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?keyYOUR_API_KEY放在请求头里X-Goog-Api-Key: YOUR_API_KEY我建议优先使用请求头方式。原因很简单URL 会被代理服务器、访问日志和浏览器历史记录下来密钥容易泄露而请求头方式至少不会出现在访问日志里。调试阶段用-H X-Goog-Api-Key: $API_KEY也更方便环境变量管理不用每次拼接字符串。注意不要把这个密钥提交到 Git 仓库也不要硬编码在脚本里。调试时用环境变量export API_KEY...配合echo $API_KEY验证是否设置成功。除了 API KeyGemini API 还支持 OAuth2 鉴权但那通常用于服务账号或企业级集成场景。本地调试用 API Key 是最快的路径没必要上来就搞 OAuth。1.2 确认模型名称版本和命名规则别搞混Gemini API 的模型名称格式是models/gemini-2.0-flash这种带版本的形式。如果你用了一个不存在的模型名服务端会返回 404错误信息类似models/gemini-2.0-flash。常见的模型后缀解释gemini-2.0-flash标准版速度快适合大多数日常任务gemini-2.5-pro加强版推理能力强但延迟更高gemini-2.0-flash-lite轻量版成本更低在我的使用中gemini-2.0-flash是通用性最好的选择。调试的时候先用它把链路跑通确认请求格式和参数都没问题后再根据需要换模型。因为不同模型的输入输出限制不同在测试参数是否有效这个阶段用哪个模型差别不大。1.3 发送你的第一个 curl 请求跑通链路把最简请求先发出去验证网络、密钥、端点三个环节是否都正常。下面的命令中$API_KEY请替换成你的真实密钥curl -sS \ -X POST \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ -d { contents: [{ parts: [{text: 说一句你好}] }] }如果一切正常你会看到类似这样的响应{ candidates: [ { content: { parts: [ {text: 你好有什么可以帮你的吗} ], role: model }, finishReason: STOP, index: 0, safetyRatings: [...] } ], usageMetadata: { promptTokenCount: 4, candidatesTokenCount: 12, totalTokenCount: 16 }, modelVersion: gemini-2.0-flash }看到candidates里有内容、finishReason是STOP就说明链路通了。如果这一步就有问题多半是网络不通或者密钥不对先别急着往下看参数。提示尽量把 API Key 放在请求头而不是 URL 参数里这样可以避免密钥出现在日志中。网络层面还有一个容易忽略的点Gemini API 的域名解析和连接在不同网络环境下差异较大建议先确认你所在的网络能正常访问该服务的域名。如果命令行长时间无响应多半是网络连通性而非 API 本身的问题。2. curl 请求参数逐项拆解从 URL 到请求体第一个请求通了之后下一步是把每个参数都搞明白。这一步的目标是当你需要修改某个行为时知道该动哪个参数、不该动哪个参数。2.1 URL 结构与方法选择POST 和 GET 的区别Gemini API 的generateContent端点使用的是 POST 方法请求数据放在 body 里。但你也可以在某些情况下使用 GET 方法把请求参数编码在 URL 的body查询参数中比如curl -sS \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key$API_KEYbody%7B%22contents%22%3A...%7D这种方式在浏览器地址栏直接调试时很管用但日常命令行调试建议还是用 POST body。原因是 URL 编码会让请求体变得难以阅读而且 URL 长度有限制长提示词会被截断。2.2 Header 设置Content-Type 与 X-Goog-Api-KeyHeader 有两个必带项Content-Type: application/json告诉服务端 body 是 JSON 格式。漏掉这个服务端可能返回 400 或无法正确解析 body。X-Goog-Api-Key: $API_KEY身份认证。你也可以把它放在 URL 的 key 参数但前面提到过放 header 更安全。调试阶段还可以临时加上-i选项让 curl 输出响应头。响应头里的x-goog-request-id字段很重要——如果你之后要联系客服或查日志这个 ID 是定位问题的最重要依据。curl -i -sS \ -X POST \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ -d {contents:[{parts:[{text:你好}]}]}2.3 请求体核心结构contents、role、parts请求体的最外层是contents数组数组里的每个元素代表一条对话消息。这个消息由role和parts组成role取值是user或model分别代表用户和模型的消息。多轮对话就是交替排列多个 contents 条目。parts消息内容的数组每个 part 可以是纯文本{text: ...}或图片{inlineData: {mimeType: image/png, data: base64...}}。最简单的单轮对话只需要一个user消息。多轮对话时把历史记录按顺序放进contents数组即可。2.4 systemInstruction给模型立规矩与内容消息不同systemInstruction放在请求体的顶层用于设定模型的整体行为。比如{ systemInstruction: { parts: [{text: 你是一个乐于助人的中文助手回答尽量简洁。}] }, contents: [ {role: user, parts: [{text: 你好介绍一下自己}]} ] }实际调试中我发现很多人会把系统指令和第一条用户消息混在一起写导致模型无法区分固定规则和当前问题。把它们分开放在不同字段里模型的遵循效果会稳定很多。2.5 generationConfig控制输出的关键参数generationConfig也是顶层字段用来控制生成行为。调试时最常用的参数{ generationConfig: { temperature: 0.7, topP: 0.95, maxOutputTokens: 200, stopSequences: [\n\n] } }需要留意的几个参数的含义temperature取值范围 0~2数值越低输出越确定越高越发散。我调试逻辑类问题时习惯设 0.2测试创意类内容时设 0.8 以上。maxOutputTokens限制输出长度防止模型长篇大论。Gemini 2.0 flash 默认输出上限较高不设置时可能一次返回上千 token调试时设小一点能避免响应过长。stopSequences停止序列。模型生成到这些字符串时会自动停止常用于控制输出格式。注意temperature和topP建议只调整一个。按官方建议两者同时调容易导致输出行为不可控。2.6 curl 自身的高频调试参数-sS静默 显示错误。-s隐藏进度条-S让错误信息仍然显示。纯-s可能在出错时让你什么都看不到。-v输出完整的请求和响应头。适合排查请求到底发出去了没有响应头里有什么这类问题。-w自定义输出格式化信息比如-w \n耗时: %{time_total}s\nHTTP状态: %{http_code}\n可以统计请求耗时和状态码。-o file把响应体保存到文件适合响应很长、屏幕滚动不便于观察的情况。-dPOST 请求体curl 会自动设置Content-Type: application/x-www-form-urlencoded但因为我们手动设置了application/json所以没问题。注意-d与--data-binary的区别前者会做一些转义处理后者原样发送。调试 JSON 时我更常用--data-binary file.json从文件读取。3. Gemini API 调用方式流式、多模态与关键参数细节这一节聊聊 Gemini API 调用中最容易踩坑的几个具体场景。非流式与流式、文本与图片、同步与异步这些选择直接决定你的调试策略。3.1 非流式与流式请求的差异前面用的generateContent端点是非流式模型会一次性返回完整响应。如果你看到响应迟迟不出是因为它在等生成完毕。流式端点streamGenerateContent则通过 Server-Sent Events 逐段返回内容。用 curl 测试流式时响应看起来是一连串的data:前缀 JSON 块curl -sS \ -X POST \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:streamGenerateContent?altsse \ -d {contents:[{parts:[{text:写一个 50 字的故事}]}]}一个常见的测试误区是把流式响应误认为是出错。如果你看到多个data:块每个里面都有部分文本那是正常的流式输出不是重复响应。流式调试时建议先不指定altsse直接看原始响应格式确认理解数据结构后再加参数。3.2 多模态图片输入base64 编码与格式声明Gemini API 支持图片输入请求时把图片转成 base64 字符串放在inlineData中{ contents: [{ parts: [ {text: 这张图里有什么}, { inlineData: { mimeType: image/jpeg, data: ...base64字符串... } } ] }] }命令行里直接用 base64 字符串构造 JSON 很不方便有个小技巧是先用base64 -w0 image.jpgLinux/macOS生成字符串然后拼接 JSON。但更好的办法是用 Python 或 jq 构造请求文件避免 shell 转义问题。调试图片输入时经常遇到两类问题一是mimeType与图片实际格式不匹配比如 JPEG 图片写成了image/png二是 base64 字符串里有换行导致 JSON 解析失败。确认图片格式可以用file image.jpg查看。3.3 reasoning 与思考能力当模型需要在回答前思考部分 Gemini 模型支持thinkingConfig配置让模型先在内部进行推理再输出最终答案。调试这类请求时响应里会包含thought部分和最终回复两个内容块比如curl -sS \ -X POST \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.5-pro:generateContent \ -d { contents: [{parts: [{text: 一个正方体有几个顶点}]}], generationConfig: { thinkingConfig: {includeThoughts: true} } }响应中的parts数组会包含两个部分thought: true的内容块和正常的text内容块。只想要最终答案的话解析时注意筛选text字段即可。3.4 请求体文件化告别 shell 转义地狱长 JSON 请求体在命令行直接写很容易出错——单引号、双引号、中文标点混在一起肉眼根本分不出哪里错了。我的做法是把请求体写到文件里然后用--data request.json发送cat request.json EOF { contents: [ {role: user, parts: [{text: 用一句话解释量子纠缠}]} ], generationConfig: { temperature: 0.3, maxOutputTokens: 100 } } EOF curl -sS \ -X POST \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ --data request.json注意--data和--data-binary在从文件读取时行为不同。--data会 strip 掉换行符--data-binary保留原始换行。JSON 本身对换行不敏感所以两种方式都可以用但如果文件里有非 ASCII 字符更推荐--data-binary以保证内容原样传输。4. Gemini API 错误码全解析从 400 到 503 的完整排查路径这个部分是最实用的。调试 Gemini API 时遇到报错最忌讳的是不知道错误码是什么意思、该往哪个方向查。我把常见错误码按请求类鉴权类资源类服务端类整理成了一张速查表并附上真实场景的排错思路。4.1 错误响应结构先学会看报错Gemini API 返回错误时响应体是一个标准结构{ error: { code: 400, message: Invalid JSON payload received..., status: INVALID_ARGUMENT, details: [...] } }code是 HTTP 状态码status是机器可读的错误类型message是人类可读的具体原因。排查时先看status再看message最后才看details。大部分情况下message已经把问题说清楚了。提示响应头里的x-goog-request-id是联系客服或排查服务端日志时的关键 ID出错时务必先把它记录下来。4.2 400 INVALID_ARGUMENT请求体格式错误这是最常见的错误。触发原因包括 JSON 语法错误、字段名拼写错误、字段类型不对、必填字段缺失。比如把contents拼成content或者把parts写成了part都会触发 400。排查思路用jq . request.json验证请求体 JSON 是否合法。如果输出报错说明 JSON 语法有问题。逐个字段核对官方文档的字段名。这一步别凭记忆直接对照文档最稳。确认数组和对象的层级关系尤其是contents是数组parts是数组两者容易混淆。4.3 400 response blocked due to safety提示词触发了安全过滤还有一种特殊的 400报错信息类似response blocked due to safety。这说明你的提示词或模型的响应触发了安全过滤。遇到这种情况需要检查请求里的文本是否包含可能被判定为敏感的内容。可以尝试调整措辞、降低语气强度或者加上这是虚构内容/教育用途等无害说明。如果仍然不行检查是否是模型回答过程中被过滤——这种情况即使问题本身无害模型也可能因为生成路径触及安全策略而中止。4.4 401 UNAUTHENTICATED 与 403 PERMISSION_DENIED密钥问题与权限问题401 的报错信息通常是API key not valid含义是密钥无效或格式不对。排查步骤确认 API Key 是否完整复制中间有没有多空格、少字符。确认服务是否已启用。密钥可能有效但服务未启用这时也会报类似错误。检查密钥是否过期或被撤销。403 的报错信息通常是Permission denied含义是密钥有效但当前上下文中无权访问该资源。常见原因是密钥所在的项目没有足够的配额权限或者使用了某个不支持当前模型的密钥。在排查 401 和 403 时有一个技巧——分别测试两种鉴权方式# 方式一URL key 参数 curl -sS https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent?key$API_KEY \ -H Content-Type: application/json \ -d {contents:[{parts:[{text:hi}]}]} # 方式二header key curl -sS https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ -d {contents:[{parts:[{text:hi}]}]}如果一种方式成功、另一种失败可以基本断定是密钥传递方式的问题而非密钥本身的问题。4.5 404 NOT_FOUND端点和模型名写错了404 通常有两类端点的 URL 路径错误比如把generateContent写成了generatecontent或者漏了:generateContent后缀模型不存在或不可用模型名称拼写错误、模型已下线、当前项目没有该模型的访问权限模型名错误的典型报错是models/gemini-2.0-flashis not found。注意检查模型名中的大小写和分隔符gemini-2.0-flash与gemini-2.0-pro是不同的模型不能混用。建议先调用模型列表接口确认当前可用的模型curl -sS \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models这个接口会返回当前项目下有权限访问的所有模型列表是排查 404 的第一利器。4.6 429 RESOURCE_EXHAUSTED配额限制与限流429 表示配额不足或请求频率超过限制。Gemini API 的限制分为每分钟请求数RPM和每分钟 token 数TPM两种维度。报错信息会提示是哪个维度超限。应对方法降低请求频率在循环调用中增加间隔减少单次请求 token 量缩短提示词、减小maxOutputTokens重试如果 429 是瞬时性的等待几秒后重试即可# 简易重试逻辑 for i in 1 2 3 4 5; do RESP$(curl -sS ... ) if echo $RESP | grep -q 429; then echo 触发限流正在重试 ($i/5) sleep 5 else echo $RESP break fi done4.7 500 INTERNAL 与 503 UNAVAILABLE服务端问题怎么处理500 表示服务端内部错误503 表示服务暂时不可用通常是因为负载过高或维护中。这两类错误不是你的问题重试是唯一的选择。技巧是使用指数退避重试——第一次等 1 秒第二次等 2 秒第三次等 4 秒以此类推。同时注意响应头里的Retry-After字段如果存在它指明了需要等待的秒数。4.8 完整错误码速查表错误码status 值含义首要排查方向400INVALID_ARGUMENT请求体格式错误JSON 合法性、字段名、类型400FAILED_PRECONDITION请求前提不满足系统指令格式、请求上下文状态401UNAUTHENTICATION密钥无效密钥完整性和有效性403PERMISSION_DENIED权限不足服务是否启用、项目配额404NOT_FOUND端点或模型不存在URL 路径、模型名称、模型列表429RESOURCE_EXHAUSTED配额超限RPM/TPM 配额、请求频率500INTERNAL服务端内部错误等待后重试503UNAVAILABLE服务不可用等待后指数退避重试5. 实战排错从现象到根因的排查路线这一节整理了几个真实调试中高频率出现的怪问题以及我是怎么一步步定位并解决的。5.1 中文提示词导致 JSON 变形现象是请求在浏览器里看着没问题但 curl 发出去就报 400。原因多数出在 shell 编码上。当你在命令行直接写-d {text: 你好}时终端的编码环境、引号嵌套、中文标点都可能造成 JSON 非法。处理方式是把请求体放到文件里用--data-binary request.json发送。文件保存为 UTF-8 无 BOM 格式。用cat创建文件时确保终端编码是 UTF-8。5.2 模型返回内容被截断现象是响应里有candidates但text内容戛然而止finishReason是MAX_TOKENS而不是STOP。这说明maxOutputTokens设置得太小输出在生成完毕前就被截断了。解决方法是调大maxOutputTokens或者在代码里对finishReason做判断——如果是MAX_TOKENS可以提示输出超长请精简回答或自动重试。调试判断的小技巧把maxOutputTokens临时设成很大的值比如 8192观察模型想说多少话。如果太长再根据实际需要调小。5.3 请求耗时过长如果-w显示time_total很大但响应体很快就拿到了问题可能出在流式解析上。如果time_starttransfer和time_total的时间差很大说明服务端思考了很久才开始返回这是模型推理耗时高与网络无关。curl -sS -o /dev/null \ -w DNS解析: %{time_namelookup}s\n建立连接: %{time_connect}s\n首字节: %{time_starttransfer}s\n总耗时: %{time_total}s\nHTTP状态: %{http_code}\n \ -X POST \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ --data request.json这个输出能帮你区分耗时瓶颈在网络还是在模型推理。time_namelookup过大说明域名解析慢time_connect过大说明 TCP 连接慢time_starttransfer之后的时间是服务端处理时间。5.4 响应内容被安全过滤调试时可能会遇到这样的情况请求正常返回 200但candidates为空或者只有promptFeedback而没有candidatespromptFeedback.blockReason字段会告诉你为什么被过滤。{ promptFeedback: { blockReason: SAFETY } }遇到这种问题先检查提示词本身有没有风险表述。有时候模型自己的回复也可能被安全机制截断表现为finishReason是SAFETY这时候调整提示词的方向或语气会有帮助。5.5 返回内容乱码或格式错误如果你用curl直接输出响应到终端中文字符偶尔显示异常。这种情况通常不是 API 的问题而是终端编码与 API 返回的 UTF-8 不匹配。可以先把响应保存到文件再查看curl -sS ... -o response.json cat response.json | jq .如果确认是 UTF-8 问题检查终端编码设置。Gemini API 所有响应都是 UTF-8 编码如果你的终端默认是其他编码需要手动切换。6. 进阶技巧把 curl 变成调试利器基础排错跑通之后可以给自己的 curl 调试加一点辅助工具让整个流程更快、更可控。6.1 用 jq 过滤和格式化响应Gemini API 的原始响应包含大量元数据safetyRatings、usageMetadata 等直接用cat查看太费眼睛。用jq可以只提取关键部分curl -sS \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ --data request.json | jq .candidates[0].content.parts[0].text这个命令只输出模型的文本回复。想看 token 消耗就换成... | jq .usageMetadata6.2 构造一个可复用的调试脚本把常用的调试流程固化成脚本能显著减少重复劳动#!/bin/bash API_KEY${API_KEY:?请先设置API_KEY环境变量} MODEL${1:-gemini-2.0-flash} PROMPT${2:-你好} cat /tmp/gemini_request.json EOF { contents: [{ parts: [{text: $PROMPT}] }], generationConfig: { temperature: 0.5, maxOutputTokens: 200 } } EOF echo 请求 cat /tmp/gemini_request.json echo -e \n 响应 curl -sS \ -X POST \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/$MODEL:generateContent \ --data-binary /tmp/gemini_request.json \ -w \n\n 统计 \nHTTP状态: %{http_code}\n总耗时: %{time_total}s\n注意脚本里用--data-binary而不是--data是为了避免 curl 对换行符做转换确保请求体与文件内容完全一致。6.3 围绕 curl 的集成测试思路当你的调试不再局限于能不能通而是想验证改了这个参数有什么效果时可以把 curl 命令批量执行。比如测试不同temperature值对输出风格的影响for t in 0.2 0.5 0.8 1.2; do echo temperature$t jq --argjson temp $t .generationConfig.temperature $temp request.json tmp.json curl -sS \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ --data-binary tmp.json | jq -r .candidates[0].content.parts[0].text echo done这种方法能帮你快速理解参数对输出行为的影响比看一眼文档更直观。6.4 日志记录与回归测试调试 API 还有一个常被忽略的需求记录每次请求和响应方便后来比对。curl 其实自带这个能力。用-w加上-o可以把响应体和耗时分开存储curl -sS \ -H Content-Type: application/json \ -H X-Goog-Api-Key: $API_KEY \ https://generativelanguage.googleapis.com/v1beta/models/gemini-2.0-flash:generateContent \ --data-binary request.json \ -o response_$(date %Y%m%d_%H%M%S).json \ -w code%{http_code} time%{time_total}\n api_debug.log这样做的好处是当某个改动导致问题出现时你可以翻看历史请求和响应找出是哪个参数发生了变化。7. 几个记忆深刻的排错实录最后分享几个实际踩坑中记忆比较深的案例每个都花了不少时间才定位到根因写出来帮你少走弯路。7.1 密钥前方多了一个空格有一次 A 同学遇到所有请求都返回 401折腾了很久密钥确认没问题、API 确认没问题后来发现是 shell 脚本里给API_KEY变量赋值时等号后面多了一个空格导致密钥串前面带着一个空格。这类看不见的字符问题非常常见肉眼很难发现。排查办法是echo [$API_KEY] # 中括号可以显示出前后是否有空格7.2 服务启用了但依然 403某次调试时密钥有效、模型存在可请求一直返回 403。检查后发现密钥对应的服务在控制台显示已启用但该模型类别需要额外开通权限。在模型列表接口里能查到模型名不代表就有完整的调用权限。这一步是很多人会忽略的。7.3 响应内容被截断的第一反应是模型有问题某次调试代码生成任务模型返回的代码总是缺了最后几行finishReason是MAX_TOKENS。一开始以为是模型能力不行后来检查发现是maxOutputTokens设成了 200而这段代码完整输出需要 300 多 token。把上限调大之后问题立刻消失。这只是设置问题而非模型问题。7.4 流式请求误判为重复输出刚接触流式接口时看到终端里一直冒出data:块第一反应是怎么返回了这么多次。实际上这是 SSE 的正常行为每个data:块是生成过程中的一个片段。不想要流式输出的话回到generateContent端点就行。8. 关于调试工具的几点个人建议工具选型方面除了 curl 本身我会常备jq和python3。jq 用来解析 JSON 响应python3 用来处理更复杂的请求构造和多轮对话测试。当 curl 命令变得很长、参数很多时用 Python 脚本替代是更高效的选择。另外浏览器开发者工具里的网络面板也可以用来调试但不适合频繁请求的场景。命令行工具的优点是容易记录、容易复现、容易脚本化这恰恰是调试和排错最需要的三件事。有一个小经验值得分享调试 API 时很多人习惯在报错后立刻修改参数重试这样反而容易越调越乱。我的习惯是先让请求稳定复现同一个错误确认无论如何都会报同样的错之后再开始逐个参数排查。稳定复现是定位问题的前提否则你可能在修补一个并不存在的问题。如果你现在正准备接入 Gemini API或者已经接入了但时不时被奇怪的报错困扰建议把这篇文章里的命令全部跑一遍把错误码速查表截图存下来。当你把每个错误都亲手触发过一次你对这套 API 的理解会上升一个台阶。