รหัสข้อผิดพลาดและการแก้ปัญหา

ระบุสิ่งที่ล้มเหลว

1. บันทึกสถานะ HTTP เมธอดคำขอ และเส้นทางจริง สถานะ HTTP และรหัสข้อผิดพลาดแอปพลิเคชันอธิบายคนละชั้น อย่าใช้แทนกัน
2. อ่านฟิลด์ข้อผิดพลาดตามโปรโตคอลที่เรียก การตอบกลับดั้งเดิม OpenAI Claude และ Gemini ไม่ได้มีโครงสร้างเดียวกันทั้งหมด
3. สำหรับคำขอสตรีม ตรวจเหตุการณ์ข้อผิดพลาดและสถานะสิ้นสุดด้วย สำหรับงานอะซิงโครนัส ตรวจ status ของงาน HTTP 200 ไม่รับประกันว่าสร้างสำเร็จ
4. ใช้ตารางด้านล่างแก้คำขอหรือตัดสินใจลองซ้ำ message เป็นข้อความอธิบาย ไม่ใช่ enum คงที่ อย่าแยกตรรกะตามถ้อยคำ

Enum รหัสข้อผิดพลาดแพลตฟอร์ม

นี่คือ enum รหัสข้อผิดพลาดแอปพลิเคชันแพลตฟอร์มทั้งหมด ชื่อเป็นป้ายอ้างอิง ค่า code ในการตอบกลับเป็นตัวเลข “HTTP ที่พบบ่อย” เป็นแนวทางแก้ปัญหา ไม่ใช่การจับคู่ตายตัวทุกเอนด์พอยต์ ใช้สถานะ HTTP และเนื้อหาตอบกลับจริง code ที่ส่งผ่านจากต้นทางอาจไม่อยู่ใน enum นี้

HTTP 429 เพียงอย่างเดียวแยกข้อจำกัดอัตรากับจำนวนพร้อมกันอย่างน่าเชื่อถือไม่ได้ แยกเมื่อมีรหัสข้อผิดพลาดตัวเลขชัดเจนเท่านั้น ตรวจตัวระบุโมเดลในรายการโมเดล อย่าเขียนค่า model ใหม่เอง

อ่านข้อผิดพลาดตามโปรโตคอล

ตัวอย่างด้านล่างแสดงโครงสร้างทั่วไปที่แพลตฟอร์มสร้าง ไม่ใช่รูปแบบเดียวที่รับประกันทุกความล้มเหลว ข้อผิดพลาดยืนยันตัวตนอาจส่งจากชั้นประมวลผลต่างกัน การส่งผ่านต้นทางอาจคงโครงสร้าง รหัสสตริง หรือชนิดของตน ระบุรูปแบบจริงก่อนแยกวิเคราะห์ หากไม่รู้จัก ให้เก็บฟิลด์เดิมและสถานะ HTTP แทนการบังคับแปลง

API ดั้งเดิมของแพลตฟอร์ม

โดยทั่วไปอ่าน error.code และ error.message อาจไม่มี requestId

{
  "success": false,
  "error": {
    "code": 10000,
    "message": "Bad request"
  },
  "requestId": "req_example"
}

บางข้อผิดพลาดอาจใช้ code และ message ระดับบน ไคลเอนต์ควรรองรับความต่างนี้ และห้ามถือว่าการไม่มีออบเจ็กต์ error พิสูจน์ความสำเร็จ การตอบกลับตรวจพารามิเตอร์อาจไม่มีรหัสตัวเลข ให้ถือรหัสที่ขาดว่าไม่ทราบแทนการสร้างขึ้นเอง

API ที่เข้ากันได้กับ OpenAI

ข้อผิดพลาดทั่วไปที่แพลตฟอร์มสร้างใช้ code, message และ type ระดับบน ไม่จำเป็นต้องอยู่ใน error

{
  "code": 40000,
  "message": "Insufficient credit",
  "type": "api_error"
}

type เป็นหมวดโปรโตคอล ส่วน code เป็นรหัสข้อผิดพลาดตัวเลขแพลตฟอร์มในโครงสร้างนี้ api_error อย่างเดียวไม่บอกว่าควรลองซ้ำหรือไม่ ข้อผิดพลาดจากการส่งผ่านต้นทางและสตรีมอาจมี error ซ้อนอยู่ จัดการตามการตอบกลับโปรโตคอลจริง ดู Chat Completions และ Responses

API ที่เข้ากันได้กับ Claude

ในโครงสร้างทั่วไป type ระดับบนเป็น error หมวดเฉพาะคือ error.type และคำอธิบายคือ error.message โครงสร้างนี้ไม่มี code ตัวเลขแพลตฟอร์ม อย่าสร้างขึ้นเอง

{
  "type": "error",
  "error": {
    "type": "invalid_request_error",
    "message": "max_tokens must be a positive safe integer"
  }
}

แพลตฟอร์มสร้างชนิดข้อผิดพลาด Claude ต่อไปนี้ภายใน นี่ไม่ใช่ enum ชนิดข้อผิดพลาดต้นทางทั้งหมด

ดู Claude Messages

ข้อผิดพลาดรูปแบบ Gemini

เมื่อได้รับการตอบกลับรูปแบบ Gemini ให้อ่าน error.code, error.message และ error.status ในที่นี้ status เป็นหมวดสตริง ไม่ใช่สถานะ HTTP หรือสถานะงานอะซิงโครนัส

{
  "error": {
    "code": 10000,
    "message": "Bad request",
    "status": "INVALID_ARGUMENT"
  }
}

ข้อผิดพลาดรูปแบบนี้ที่แพลตฟอร์มสร้างใช้ค่า code ตัวเลขแพลตฟอร์ม การจับคู่ status สตริงภายในอยู่ด้านล่าง ไม่ใช่ enum สถานะต้นทางทั้งหมด

503 มีลำดับก่อนและใช้ UNAVAILABLE ไม่ใช่ INTERNAL การตอบกลับต้นทางอาจใช้ความหมาย code และ status ต่างกัน อย่าใช้ตารางรหัสแพลตฟอร์มกับทุกโค้ดตัวเลข Gemini

ลองซ้ำอย่างปลอดภัย

ปฏิบัติตามเฮดเดอร์ Retry-After ที่ถูกต้องเมื่อมี อย่าคิดว่าทุกข้อผิดพลาดมี การลองคำขอสร้างที่ไม่เป็น idempotent ซ้ำอัตโนมัติอาจดำเนินการอีกและเกิดค่าใช้จ่ายเพิ่ม หน้านี้ไม่รับรองการรองรับคีย์ idempotency ทั่วไป การเพิ่ม Idempotency-Key เองไม่รับประกันป้องกันซ้ำ

หากมี jobId แล้ว ตรวจงานนั้นก่อนสร้างใหม่ หากไม่มี jobId และผลไม่แน่นอน เก็บตัวระบุคำขอและเวลาไว้สืบค้น

สตรีมและงานอะซิงโครนัส

คำขอ SSE

หลัง SSE เริ่ม สถานะ HTTP อาจคง 200 ขณะที่ความล้มเหลวภายหลังรายงานผ่านเหตุการณ์ข้อผิดพลาดหรือข้อมูลในสตรีม แยกเหตุการณ์และข้อมูลตามโปรโตคอลที่เลือกและตรวจการจบปกติ เมื่อมีข้อผิดพลาดหรือหลุดผิดคาด อย่าถือข้อความหรือภาพบางส่วนเป็นผลสำเร็จสมบูรณ์ ชื่อเหตุการณ์และข้อมูลต่างกันตามเอนด์พอยต์ อย่าตรวจเพียงฟิลด์ error คงที่หรือใช้ “ได้รับข้อความอะไรก็ได้” เป็นเงื่อนไขสำเร็จ

งานอะซิงโครนัส

การตอบกลับสร้างที่มี data.jobId หมายถึงรับคำขอแล้ว ไม่ใช่สร้างเสร็จ การตอบกลับ HTTP สำเร็จเมื่อตรวจงาน หมายถึงการตรวจสำเร็จ ยังต้องตรวจ data.status ของงาน:

• PENDING, CONNECT, PROCESSING: ตรวจสถานะต่อไปตามเอกสาร Jobs
• COMPLETED: อ่าน outputResult
• FAILED, CANCELLED: หยุดตรวจและเก็บ ID งานกับข้อมูลตอบกลับที่ลบข้อมูลอ่อนไหวแล้วไว้สืบค้น

รายละเอียดล้มเหลวอาจปรากฏใน data.outputResult.error ฟิลด์นี้เป็นตัวเลือก ไม่รับประกันทุกงานล้มเหลว ใช้ Jobs เมื่อการตอบกลับสร้างส่ง jobId ชัดเจนเท่านั้น อย่าใช้การตรวจงานกับเอนด์พอยต์ที่ส่งผลโดยตรงผ่าน JSON หรือ SSE

ข้อมูลวินิจฉัยสำหรับผู้ใช้และผู้ช่วย AI

ส่งข้อมูลต่อไปนี้ที่ลบข้อมูลอ่อนไหวแล้วให้ฝ่ายสนับสนุนหรือผู้ช่วย AI ใช้ unknown สำหรับฟิลด์ที่ไม่มี ใช้ unknown สำหรับสถานะ HTTP หากไม่ได้รับการตอบกลับ HTTP เก็บเส้นทางฟิลด์และชนิดค่าดั้งเดิม เช่น error.code: 10000 (number) หรือ error.code: "invalid_api_key" (string) อย่าแปลง code สตริงเป็นรหัสตัวเลขแพลตฟอร์มอัตโนมัติหรือสร้างฟิลด์ที่ขาดจาก message สถานะ HTTP หรือชื่อโมเดล

time_with_timezone: unknown
method: unknown
path_without_query: unknown
model: unknown
stream: unknown
http_status: unknown
error_code_path_value_and_type: unknown
error_type_path_and_value: unknown
protocol_status_path_and_value: unknown
sanitized_message: unknown
request_id_from_body_or_X-Request-ID: unknown
job_id: unknown
job_status: unknown
retry_after: unknown
retry_count_and_delays: unknown
received_partial_output: unknown

อ่าน requestId จากเนื้อหาตอบกลับหรือเฮดเดอร์ตอบกลับ X-Request-ID เมื่อมี เก็บ jobId เป็นสตริงเพื่อไม่เสียความแม่นยำตัวเลขยาว ให้พารามิเตอร์คำขอเท่าที่จำเป็นและลบข้อมูลอ่อนไหวแล้ว ลบคีย์ API โทเคน คุกกี้ เฮดเดอร์ยืนยันตัวตนเต็ม ข้อมูลส่วนบุคคล พรอมต์ส่วนตัว และเนื้อหาไฟล์อินพุต ลบพารามิเตอร์คิวรี URL และ URL อินพุตหรือเอาต์พุตที่มีลายเซ็นหรือข้อมูลรับรอง อย่าวางบันทึกคำขอทั้งหมดโดยไม่ตรวจ

ผู้ช่วย AI ควรแยกฟิลด์ที่สังเกตได้จากสาเหตุที่เป็นไปได้และระบุข้อมูลที่ขาด หลักฐานไม่พอต้องไม่ถูกถือว่าพิสูจน์คำขอสำเร็จ ไม่ได้ดำเนินการ หรือไม่มีค่าใช้จ่าย