เอกสารอ้างอิง API

รหัสข้อผิดพลาด

หน้านี้แปลด้วยเครื่องจากเวอร์ชันภาษาจีน อาจมีข้อผิดพลาด โปรดยึดเวอร์ชันภาษาจีนเป็นหลัก

เมื่อเกิดข้อผิดพลาด API จะส่งคืน errorId: 1 โดย errorCode คือรหัสข้อผิดพลาด และ errorDescription คือคำอธิบายเป็นข้อความ คำขอที่ส่งคืนข้อผิดพลาดจะไม่ถูกหักพอยต์ หากเกิดข้อผิดพลาดตั้งแต่ตอนสร้างงานจะไม่หักพอยต์ และหากสร้างงานแล้วแต่จดจำไม่สำเร็จหรือหมดเวลา ระบบจะคืนพอยต์ให้อัตโนมัติ

{
  "errorId": 1,
  "errorCode": "ERROR_ZERO_BALANCE",
  "errorDescription": "帐户余额不足"
}

หลักการจัดการ

ข้อผิดพลาดด้านพารามิเตอร์ (รูปแบบคำขอ ClientKey ประเภทงาน พารามิเตอร์เว็บไซต์ รูปภาพ) ส่งซ้ำก็ไม่ได้ผลลัพธ์ที่ต่างไป ต้องแก้คำขอก่อน
การจดจำไม่สำเร็จและหมดเวลา (ERROR_CAPTCHA_UNSOLVABLE, ERROR_TASK_TIMEOUT) สามารถสร้างงานใหม่ได้
เมื่อเกิดข้อผิดพลาด ให้หยุด polling taskId นั้น และอย่าส่งคำขอเดิมซ้ำถี่ ๆ
ข้อผิดพลาดที่ทำเครื่องหมาย “นับรวมการหยุดชั่วคราวอัตโนมัติ” หาก clientKey เดียวกันเกิดข้อผิดพลาดนี้ 100 ครั้งภายในหนึ่งนาที จะถูกหยุดการสร้างงานชั่วคราว 5 นาที ส่วนข้อผิดพลาดที่ทำเครื่องหมาย “แคช” จะไม่นับรวม แต่ในช่วงที่แคชยังมีผล คำขอเดิมจะได้รับข้อผิดพลาดเดิมทันที ดูรายละเอียดที่ ขีดจำกัดงานพร้อมกันและการหยุดชั่วคราวอัตโนมัติ

รหัสข้อผิดพลาดทั้งหมด

รูปแบบคำขอ

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_REQUIRED_FIELDS`	ขาดฟิลด์ที่จำเป็น (เช่น `clientKey` หรือ `websiteURL` / `websiteKey` ที่ประเภทงานนั้นต้องการ) หรือเนื้อหาคำขอไม่ใช่ JSON	เพิ่มฟิลด์ที่ขาดตามที่ระบุในหน้าประเภทงาน และส่ง JSON ด้วย `POST` พร้อม `Content-Type: application/json`
`ERROR_REQUEST_FORMATS` นับรวมการหยุดชั่วคราว	เนื้อหาคำขอไม่ใช่ JSON ที่ถูกต้อง	สร้างเนื้อหาคำขอด้วยไลบรารี JSON แทนการต่อสตริงเอง และใน JSON ห้ามมีคอมเมนต์ `//`
`ERROR_TASK_ABSENT` นับรวมการหยุดชั่วคราว	ไม่มีฟิลด์ `task` ในการเรียก `createTask`	ใส่พารามิเตอร์ของงานไว้ในออบเจ็กต์ `task` หากใช้ Python requests ให้ใช้ `json=data` ไม่ใช่ `data=data`
`ERROR_TASK_NOT_SUPPORTED` นับรวมการหยุดชั่วคราว	`task.type` สะกดผิด หรือประเภทงานนี้ถูกยกเลิกแล้ว	คัดลอกชื่อประเภทงานจาก "ประเภทงานและราคา" โดยชื่อแยกแยะตัวพิมพ์เล็กพิมพ์ใหญ่
`ERROR_PAGE_NOT_FOUND`	ไม่มีเส้นทางที่ร้องขอ	ตรวจสอบ URL ของ endpoint เช่น `https://api.yescaptcha.com/createTask` ชื่อเมธอดแยกแยะตัวพิมพ์เล็กพิมพ์ใหญ่
`ERROR_BAD_REQUEST`	ไม่สามารถประมวลผลคำขอได้ มักเกิดจาก HTTP method ไม่ถูกต้อง (ใช้ GET แทน POST) หรือค่าพารามิเตอร์ไม่ถูกต้อง	ส่ง JSON ด้วย `POST` และตรวจสอบชนิดและค่าของพารามิเตอร์
`ERROR_ILLEGAL_PARAMETERS`	ค่าพารามิเตอร์ไม่ถูกต้อง พบบ่อยกับหน้าตรวจสอบของ Cloudflare: `websiteURL` ไม่ใช่ URL สาธารณะที่ขึ้นต้นด้วย `http://` / `https://`, `postData` ไม่ใช่ออบเจ็กต์ หรือ `requiredCookies` ไม่ใช่อาร์เรย์ของสตริง (คืนโดย createTask ไม่หักพอยต์) หรือไม่สามารถ resolve โดเมนเป้าหมายผ่านพร็อกซีได้ (คืนโดย getTaskResult คืนพอยต์ให้อัตโนมัติ)	แก้ไขค่าตามตารางพารามิเตอร์ในหน้าประเภทงาน หากไม่สามารถ resolve โดเมนได้ ให้ตรวจสอบการสะกด URL และดูว่าพร็อกซีเข้าถึงเว็บไซต์นั้นได้หรือไม่

บัญชีและยอดคงเหลือ

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_KEY_DOES_NOT_EXIST` นับรวมการหยุดชั่วคราว	ไม่มี `clientKey` นี้อยู่: ตัวอักษรเกินหรือหายไปตอนคัดลอก หรือคีย์ถูกรีเซ็ตในแดชบอร์ดแล้ว	คัดลอกคีย์ใหม่จากแดชบอร์ดของ yescaptcha.com โดยไม่มีช่องว่างหรือการขึ้นบรรทัดใหม่
`ERROR_KEY_EXPIRED` นับรวมการหยุดชั่วคราว	`clientKey` หมดอายุแล้ว (ส่งกลับจาก createTask และ getBalance โดยไม่หักพอยต์) มี 2 กรณี: ไม่ได้ใช้งานเป็นเวลานาน ระบบจึงกำหนดเวลาหมดอายุเพื่อปกป้องบัญชี (จะส่งอีเมลแจ้งเตือนก่อนหมดอายุ) หรือเลยเวลาหมดอายุที่ตั้งไว้สำหรับ `clientKey` นี้แล้ว	เข้าสู่ระบบแดชบอร์ดที่ yescaptcha.com หากหมดอายุเพราะไม่ได้ใช้งานเป็นเวลานาน ให้สร้าง `clientKey` ใหม่ ยอดคงเหลือจะย้ายไปยัง `clientKey` ใหม่โดยอัตโนมัติ หากมีการตั้งเวลาหมดอายุไว้ ให้ปรับเวลาหมดอายุหรือใช้ `clientKey` อื่น จากนั้นอัปเดตโปรแกรมของคุณด้วย `clientKey` ใหม่
`ERROR_KEY_IP_NOT_ALLOWED`	`clientKey` นี้ตั้งค่า allowlist ของ IP ไว้ และ IP ที่ส่งคำขอไม่อยู่ในรายการ (คืนค่าจาก createTask และ getBalance ไม่หักพอยต์ ไม่นับรวมการหยุดชั่วคราวอัตโนมัติ)	เข้าสู่ระบบแดชบอร์ดของ yescaptcha.com แล้วเพิ่ม IP สาธารณะของเครื่องที่ส่งคำขอลงใน allowlist ของ `clientKey` นี้ หรือใช้ `clientKey` อื่น หากเรียกใช้ API จากหลายเครื่อง ให้เพิ่ม IP สาธารณะของทุกเครื่อง (หมายถึง IP ที่เรียก API ของ YesCaptcha ไม่เกี่ยวกับพร็อกซีในพารามิเตอร์ของงาน)
`ERROR_KEY_QUOTA_EXCEEDED`	`clientKey` นี้ตั้งขีดจำกัดการใช้จ่ายไว้ และขีดจำกัดที่เหลือในรอบปัจจุบันไม่พอสำหรับค่าใช้จ่ายของงานนี้ (คืนค่าจาก createTask ไม่หักพอยต์ ไม่นับรวมการหยุดชั่วคราวอัตโนมัติ) ขีดจำกัดนับตามพอยต์ที่หักจริง พอยต์ที่คืนจากงานที่ล้มเหลวหรือหมดเวลาจะคืนกลับเข้าขีดจำกัดด้วย	เข้าสู่ระบบแดชบอร์ดของ yescaptcha.com แล้วเพิ่มขีดจำกัดของ `clientKey` นี้ รอรอบถัดไป (รีเซ็ตทุกวัน ทุกวันจันทร์ หรือวันที่ 1 ของทุกเดือน ตามเวลาปักกิ่ง ขีดจำกัดแบบครั้งเดียวไม่รีเซ็ต) หรือใช้ `clientKey` อื่น `getBalance` จะคืนค่าขีดจำกัดที่เหลือของ `clientKey` นี้ (`keyQuotaRemaining`)
`ERROR_ZERO_BALANCE`	ยอดคงเหลือไม่เพียงพอ ต้องมียอดคงเหลือมากกว่า 10 พอยต์จึงจะสร้างงานได้	เติมเงินแล้วลองใหม่ ใช้ `getBalance` เพื่อตรวจสอบยอดคงเหลือ

งานพร้อมกันและการหยุดชั่วคราว

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_THREADS_MAXIMUM` บางกรณีนับรวมการหยุดชั่วคราว	บัญชีนี้มีงานประเภทนี้กำลังประมวลผลอยู่พร้อมกันมากเกินไป `limit` ในการตอบกลับคือขีดจำกัดงานพร้อมกันปัจจุบัน คำขอนี้ไม่ได้รับการประมวลผลและไม่หักพอยต์	รอให้คำขอที่ส่งไปแล้วได้รับผลลัพธ์ก่อน หรือรอ 1-2 วินาทีแล้วลองใหม่ และจำกัดจำนวนคำขอที่รอผลพร้อมกันในโปรแกรมของคุณ
`ERROR_IP_BLOCKED_5MIN`	`clientKey` นี้เกิดข้อผิดพลาดมากเกินไปในเวลาสั้น ๆ จึงถูกหยุดชั่วคราวอัตโนมัติ `retryAfter` คือจำนวนวินาทีที่เหลือ และ `blockReason` คือรหัสข้อผิดพลาดที่ทำให้ถูกหยุด	แก้ไขคำขอตาม `blockReason` แล้วรอ `retryAfter` วินาที การส่งคำขอระหว่างที่หยุดชั่วคราวจะไม่ทำให้เวลานานขึ้น
`ERROR_NO_SLOT_AVAILABLE`	บริการจดจำกำลังมีภาระงานสูงชั่วคราว หากส่งคืนจาก createTask จะไม่มีการหักพอยต์ ส่วนงานที่รอในคิวนานเกินไปจะส่งคืนข้อผิดพลาดนี้จาก getTaskResult เช่นกัน และคืนพอยต์ให้อัตโนมัติ	รอสักครู่แล้วสร้างงานใหม่อีกครั้ง

งานและผลลัพธ์

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_TASKID_INVALID` นับรวมการหยุดชั่วคราว	ไม่มี `taskId` นี้อยู่ หมดอายุแล้ว (ผลลัพธ์เก็บไว้ประมาณ 10 นาที) เป็นของ `clientKey` อื่น หรือถูกสร้างบน endpoint อีกฝั่ง	หยุด polling (เรียกตรวจซ้ำเป็นระยะ) งานนี้ แล้วตรวจสอบด้วย endpoint และ `clientKey` เดียวกับที่ใช้สร้างงาน
`ERROR_TASK_TIMEOUT`	งานไม่เสร็จภายในเวลาที่กำหนด (โดยปกติ 110 วินาที) และคืนพอยต์ให้อัตโนมัติแล้ว	สร้างงานใหม่ หากหมดเวลาซ้ำๆ ให้ลองใช้ประเภทงานอื่นสำหรับ CAPTCHA แบบเดียวกัน
`ERROR_CAPTCHA_UNSOLVABLE`	ครั้งนี้ไม่สามารถจดจำ CAPTCHA ได้ และคืนพอยต์ให้แล้ว ข้อผิดพลาดนี้ไม่นับรวมในการหยุดชั่วคราวอัตโนมัติ	สร้างงานใหม่ หากยังล้มเหลวต่อเนื่อง ให้ตรวจสอบ `websiteURL` `websiteKey` และพารามิเตอร์อื่นๆ หรือลองใช้ประเภทงานอื่นสำหรับ CAPTCHA แบบเดียวกัน
`ERROR_SETTLEMENT_FAILED` นับรวมการหยุดชั่วคราว	ยอดคงเหลือไม่เพียงพอ ณ ตอนชำระยอด จึงไม่ได้ส่งคืนผลลัพธ์	เติมเงินแล้วสร้างงานใหม่
`ERROR_NO_SUCH_CAPCHA_ID`	งานนี้ใช้งานไม่ได้อีกต่อไป	หยุด polling (เรียกตรวจซ้ำเป็นระยะ) งานนี้ แล้วสร้างงานใหม่
`ERROR_RECAPTCHA_TIMEOUT`	การจดจำ CAPTCHA หมดเวลา และคืนพอยต์ให้อัตโนมัติแล้ว	สร้างงานใหม่

พารามิเตอร์ของเว็บไซต์เป้าหมาย

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_RECAPTCHA_INVALID_SITEKEY` แคช ไม่นับรวมการหยุดชั่วคราว	`websiteKey` ไม่ถูกต้อง	ค้นหา sitekey ในหน้าเว็บอีกครั้ง (ดูคู่มือการค้นหาพารามิเตอร์) คำขอที่เหมือนกันทุกประการจะได้รับข้อผิดพลาดนี้ทันทีในช่วงที่แคชยังมีผล พร้อม `cached: true` ในการตอบกลับ
`ERROR_RECAPTCHA_INVALID_DOMAIN` แคช ไม่นับรวมการหยุดชั่วคราว	โดเมนของ `websiteURL` ไม่ตรงกับ `websiteKey`	ใส่ `websiteURL` เป็นที่อยู่ของหน้าเว็บที่แสดง CAPTCHA
`ERROR_INVALID_KEY_TYPE` แคช ไม่นับรวมการหยุดชั่วคราว	sitekey เป็นของ CAPTCHA อีกประเภทหนึ่ง เช่น ใช้ key ของ v3 กับประเภทงานของ v2	ระบุประเภทของ CAPTCHA ก่อน (ดู "วิธีระบุประเภท CAPTCHA") แล้วเลือกประเภทงานที่ตรงกัน สำหรับ v2 แบบ invisible ให้ตั้งค่า `isInvisible`
`ERROR_DOMAIN_NOT_ALLOWED` แคช ไม่นับรวมการหยุดชั่วคราว	ยังไม่รองรับเว็บไซต์นี้	ลองใช้ประเภทงานอื่นสำหรับ CAPTCHA แบบเดียวกัน หรือติดต่อฝ่ายสนับสนุน
`ERROR_HIGH_DEMAND_DOMAIN` นับรวมการหยุดชั่วคราว	ยังไม่รองรับเว็บไซต์นี้	หยุดส่งงานของเว็บไซต์นี้ และติดต่อฝ่ายสนับสนุน
`ERROR_FAILED_LOADING_WIDGET`	ไม่สามารถโหลด CAPTCHA ด้วยพารามิเตอร์ที่ระบุได้	ตรวจสอบ `websiteURL` และ `websiteKey` สำหรับประเภทงานที่ใช้พร็อกซีของคุณเอง ให้ตรวจสอบว่าพร็อกซีเข้าถึงเว็บไซต์ได้

ภาพ

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_ZERO_CAPTCHA_FILESIZE` นับรวมการหยุดชั่วคราว	รูปภาพว่างเปล่าหรือเล็กเกินไป	ตรวจสอบว่าข้อมูล Base64 ครบถ้วนและไม่มีคำนำหน้า `data:image/...;base64,`
`ERROR_TOO_BIG_CAPTCHA_FILESIZE` นับรวมการหยุดชั่วคราว	รูปภาพมีขนาดใหญ่เกินไป	บีบอัดหรือย่อรูปภาพ โดยเนื้อหาคำขอทั้งหมดต้องมีขนาดไม่เกิน 6 MB
`ERROR_IMAGE_TYPE_NOT_SUPPORTED` นับรวมการหยุดชั่วคราว	ไม่รองรับรูปแบบของรูปภาพ หรือรูปภาพนี้ไม่ใช่ชนิดที่ประเภทงานนี้ประมวลผลได้ หากเกิดขึ้นเพียงครั้งเดียว ClientKey จะถูกหยุดชั่วคราว 30 นาที	ใช้ JPG หรือ PNG และตรวจสอบว่ารูปภาพตรงกับประเภทงาน เช่น การจดจำภาพของ reCAPTCHA ต้องใช้ขนาด 100x100, 300x300 หรือ 450x450
`ERROR_ILLEGAL_IMAGE` นับรวมการหยุดชั่วคราว	ขนาดรูปภาพไม่ตรงตามข้อกำหนดของประเภทงานนี้	ปรับขนาดรูปภาพตามที่อธิบายไว้ในหน้าของประเภทงาน
`ERROR_PARSE_IMAGE_FAIL`	ไม่สามารถถอดรหัสรูปภาพได้ มักเกิดจาก Base64 ไม่ครบถ้วนหรือมีคำนำหน้า	ตรวจสอบการเข้ารหัส Base64 และลบคำนำหน้า `data:` กับการขึ้นบรรทัดใหม่ออก
`ERROR_UNKNOWN_QUESTION`	`question` ไม่ถูกต้อง หรือยังไม่รองรับคำถามนี้	ตรวจสอบกับรายการคำถามในหน้าของประเภทงาน หากเป็นคำถามที่ไม่รองรับ ให้ติดต่อฝ่ายสนับสนุน โดยปกติคำถามใหม่จะได้รับการรองรับภายใน 3 วันทำการ
`ERROR_UNKNOW_450x450_QUESTION`	คำถามนี้ยังไม่รองรับรูปภาพ 4x4 (450x450)	โหลดโจทย์ในหน้าเว็บใหม่เพื่อให้ได้คำถามอื่น

พร็อกซี

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_PROXY_CONNECT_REFUSED`	พร็อกซีปฏิเสธการเชื่อมต่อ	ตรวจสอบที่อยู่ พอร์ต และโปรโตคอลของพร็อกซี และตรวจสอบว่ารับการเชื่อมต่อจากภายนอกได้ (ต้องไม่ใช่ที่อยู่ภายในเครื่อง เช่น 127.0.0.1)
`ERROR_PROXY_CONNECT_TIMEOUT`	การเชื่อมต่อกับพร็อกซีหมดเวลา	ใช้พร็อกซีที่เสถียรกว่านี้
`ERROR_PROXY_READ_TIMEOUT`	การอ่านข้อมูลผ่านพร็อกซีหมดเวลา	ใช้พร็อกซีที่เร็วกว่านี้
`ERROR_PROXY_BANNED`	พร็อกซีใช้งานไม่ได้ หรือ IP ของพร็อกซีถูกเว็บไซต์เป้าหมายบล็อก	ใช้พร็อกซีอื่น
`ERROR_PROXY_INCORRECT`	รูปแบบของพารามิเตอร์พร็อกซีไม่ถูกต้อง	ตรวจสอบรูปแบบของ `proxyType` `proxyAddress` `proxyPort` (หรือสตริง `proxy`)
`ERROR_PROXY_TRANSPARENT`	พร็อกซีเป็นแบบโปร่งใส (transparent) และเปิดเผย IP จริง	ใช้พร็อกซีแบบ anonymous (elite)
`ERROR_PROXY_NOT_AUTHORISED`	ชื่อผู้ใช้หรือรหัสผ่านของพร็อกซีไม่ถูกต้อง	ตรวจสอบ `proxyLogin` และ `proxyPassword` (หรือข้อมูลเข้าสู่ระบบในสตริง `proxy`)
`ERROR_PROXY_TLS_ERROR`	การทำ TLS handshake กับพร็อกซีล้มเหลว มักเกิดจาก `proxyType` ไม่ถูกต้อง (เช่น ตั้งเป็น https สำหรับพร็อกซี http)	ตรวจสอบโปรโตคอลของพร็อกซี
`ERROR_PROXY_CONNECTION_FAILED`	ไม่สามารถเชื่อมต่อกับเซิร์ฟเวอร์พร็อกซีได้	ตรวจสอบที่อยู่และพอร์ตของพร็อกซี และตรวจสอบว่าพร็อกซีทำงานปกติ

เซิร์ฟเวอร์

รหัสข้อผิดพลาด	ความหมาย	วิธีแก้ไข
`ERROR_SERVICE_UNAVALIABLE`	บริการไม่พร้อมใช้งานชั่วคราว (รหัสข้อผิดพลาดสะกดว่า `UNAVALIABLE`)	ลองใหม่ภายหลัง หากยังเกิดขึ้นต่อเนื่อง โปรดติดต่อฝ่ายสนับสนุน
`ERROR_INTERNAL_SERVER_ERROR`	เกิดข้อผิดพลาดภายในเซิร์ฟเวอร์	ลองใหม่ภายหลัง หากยังเกิดขึ้นอีก โปรดติดต่อฝ่ายสนับสนุนพร้อมแจ้ง `taskId`
`ERROR_UNKNOWN`	ข้อผิดพลาดที่ยังไม่ได้จัดประเภท	ลองใหม่ภายหลัง หากยังเกิดขึ้นอีก โปรดติดต่อฝ่ายสนับสนุนพร้อมแจ้ง `taskId`

ฟิลด์เพิ่มเติม

ข้อผิดพลาดบางรายการจะมีฟิลด์เพิ่มเติมในการตอบกลับ:

ฟิลด์	ปรากฏใน	คำอธิบาย
`retryAfter`	`ERROR_IP_BLOCKED_5MIN`, ข้อผิดพลาดที่แคชไว้	ต้องรออีกกี่วินาที
`blockReason`	`ERROR_IP_BLOCKED_5MIN`	รหัสข้อผิดพลาดที่ทำให้ถูกหยุดชั่วคราว
`blockDetail`	`ERROR_IP_BLOCKED_5MIN`	ประเภท URL และ sitekey ของคำขอที่ทำให้ถูกหยุดชั่วคราว เพื่อช่วยระบุสาเหตุ
`cached`	ข้อผิดพลาดที่แคชไว้	เป็น `true` หมายถึงนี่เป็นผลลัพธ์จากแคช ไม่ได้มีการจดจำจริง
`badRequest`	ข้อผิดพลาดที่แคชไว้	พารามิเตอร์ที่ตรงกับแคช
`limit`	`ERROR_THREADS_MAXIMUM`	ขีดจำกัดงานพร้อมกันในปัจจุบันของคุณ

กฎเรื่องภาษาของ errorDescription ดูได้ที่ คำขอและการตอบกลับ