เริ่มต้น
ข้อผิดพลาดและเพดาน
รูปของคำตอบที่ผิดพลาด อัตราที่ยิงได้ และเส้นแบ่งระหว่าง “ตอบน้อยลง” กับ “ไม่ตอบ”
รูปของข้อผิดพลาด
{ "error": "\"size\" is a whole number, 0 or more" }ข้อความเป็นภาษาอังกฤษทั้งหมด และเป็นประโยคให้คนอ่าน ไม่ใช่รหัส — บอกว่าผิดตรงไหนและต้องส่งอะไรแทน · ไม่มีการสะท้อนเนื้อคำขอกลับมา แม้คำขอจะใหญ่แค่ไหน
ข้อผิดพลาดที่มาจากเอนจินมีคีย์ from: "engine" ติดมาด้วย · ข้อความของเอนจินถูกส่งต่อ โดยตัดสิ่งที่เป็นของภายในออก — ชื่อที่เอนจินใช้เรียกชุดข้อมูลของคุณ ฟิลด์ภายในของมัน และคำแนะนำให้ตั้งค่าที่มีแต่ผู้ดูแลเอนจินทำได้
รหัสที่จะเจอ
| ฟิลด์ | ความหมาย |
|---|---|
400 | คำขอผิด — เนื้อคำขอไม่ใช่ JSON, ขาดฟิลด์ที่ต้องมี, ค่าอยู่นอกช่วง (เช่น size ติดลบ), DSL ที่เอนจินปฏิเสธ, หัวข้อ X-End-User ที่ผิดรูป, พารามิเตอร์ใน URL ที่เส้นนั้นไม่อ่าน (ทุกเส้นของ /v1 ตรวจก่อนทำอะไร จึงไม่มีอะไรเปลี่ยน · ตัวเลือกอย่าง dry_run อยู่ในเนื้อคำขอ) · ลองซ้ำแล้วก็ได้คำตอบเดิม |
401 | ไม่มีคีย์ หรือคีย์ใช้ไม่ได้ · มาพร้อม WWW-Authenticate และบอกว่าผิดแบบไหน (ไม่มี, ผิด scheme, ส่งสองตัว, ถูกเพิกถอน) |
402 | ไม่ใช่ “ช้าลงหน่อย” แต่เป็น “แพ็กเกจนี้ทำไม่ได้” หรือ “โควตาเดือนนี้หมด” — ลองใหม่แล้วก็ได้คำตอบเดิม |
403 | คีย์นี้ทำสิ่งนี้ไม่ได้ — client key ในเส้นที่ต้องใช้ service key, client key จากหน้าเว็บที่ไม่อยู่ในรายการ, explain ด้วย client key, X-End-User กับ client key, หรือคีย์ใดก็ตามที่เส้นของคอนโซลใต้ /api |
404 | ไม่มีเส้นนี้ (รวมถึงเส้นที่มี / ท้าย), ไม่มีระเบียน id นี้, หรือ /v1/filters/:field ของฟิลด์ที่ไม่ใช่ตัวกรอง |
405 | เส้นนี้มีอยู่ แต่ใช้ method อื่น · มาพร้อม Allow |
409 | Idempotency-Key เดิมกำลังทำงานอยู่หรือเคยใช้กับคำขออื่น · เปลี่ยน id_field หลังมีข้อมูลแล้ว · ชื่อคอลัมน์หมวดชนกับคอลัมน์ที่มีอยู่ |
413 | เนื้อคำขอใหญ่เกินเพดานของเส้นนั้น (ส่งระเบียน 32 MB, ค้นหา 1 MB) — ข้อความบอกขนาด และมี CORS ให้เบราว์เซอร์อ่านได้ |
415 | เนื้อคำขอไม่ได้ส่งเป็น application/json |
429 | ยิงถี่เกินอัตราของคีย์ หรือเกินส่วนแบ่งของผู้เข้าชมคนนั้น — ข้อความบอกว่าเกินของใคร (this plan, this visitor's share, this end user's share) · มี Retry-After มาด้วยเสมอ และเบราว์เซอร์อ่านได้ |
502 | เอนจินทำงานไม่สำเร็จ — sync หรือการเปลี่ยนโครงที่ล้ม ของเดิมยังอยู่ครบ ลองซ้ำได้ |
503 | เอนจินไม่ตอบ — ลองใหม่ได้ |
402 กับ 429 ต่างกันตรงที่ควรลองใหม่ไหม
429 แล้วรอตาม Retry-After คือไคลเอนต์ที่ทำถูก ส่วนตัวที่เจอ 402 แล้ววนลองใหม่คือไคลเอนต์ที่กำลังยิงกำแพง · ไม่มี 500 ที่เกิดจากคำขอของคุณ — ถ้าเจอ ข้อความมีรหัสอ้างอิงให้แจ้งเราอัตราต่อวินาที
นับต่อ คีย์ ไม่ใช่ต่อบัญชี — คีย์ที่หลุดออกไปจะจำกัดตัวมันเองโดยไม่ลากคีย์อื่นลงไปด้วย · ผู้เข้าชมที่บอกได้ว่าเป็นใครได้ถังของตัวเองหนึ่งในสี่ของอัตราของคีย์ และยังนับในถังของคีย์ด้วย รวมกันจึงไม่เกินอัตราของคีย์ และคนเดียวใช้ของทั้งร้านหมดไม่ได้
| ฟิลด์ | ความหมาย |
|---|---|
Free20/s | ต่อคีย์ · ผู้เข้าชมแต่ละคน 5/s |
Starter50/s | ต่อคีย์ · ผู้เข้าชมแต่ละคน 12.5/s |
Growth200/s | ต่อคีย์ · ผู้เข้าชมแต่ละคน 50/s |
Scale1,000/s | ต่อคีย์ · ผู้เข้าชมแต่ละคน 250/s |
| ฟิลด์ | ความหมาย |
|---|---|
client key + Origin | เบราว์เซอร์ แยกตาม IP — แต่ละคนได้ถังหนึ่งในสี่ของอัตราของคีย์ (อย่างน้อย 2/s) ร้านไม่ต้องทำอะไร |
service key + X-End-User | หน้าที่เรนเดอร์บนเซิร์ฟเวอร์ ทุกคนมาจากเครื่องเดียว จึงส่งหัวข้อ X-End-User เป็น id ทึบของผู้เข้าชมหรือ IP ของเขา (ไม่ใช่อีเมล) — แต่ละค่าได้ถังหนึ่งในสี่เหมือนกัน · ตัวอักษร A–Z a–z 0–9 . _ : - ยาว 1–128 ไม่อย่างนั้นได้ 400 ที่บอกชื่อหัวข้อและกติกา |
client key + X-End-User | 403 — ใครอ่าน client key จากหน้าเว็บได้ก็ตั้งชื่อใหม่ได้ทุกคำขอ ส่วนแบ่งจะไม่จำกัดอะไรเลย · client key แยกผู้เข้าชมด้วย IP อยู่แล้ว |
ไม่บอกว่าใคร | คำขอจากเซิร์ฟเวอร์ที่ไม่มี X-End-User ใช้ถังของคีย์ทั้งถัง คนเดียวที่เปิดหลายแท็บจึงทำให้ทุกคนได้ 429 ได้ |
โควตารายเดือน — อะไรนับอะไร
นับตามเดือนปฏิทิน (UTC) และเริ่มนับใหม่วันที่ 1 · เมื่อโควตาหมด การค้นยังตอบด้วยแบบที่ถูกกว่าพร้อม degraded ส่วนการเขียนได้ 402
| ฟิลด์ | ความหมาย |
|---|---|
ค้นหาFree 10,000 · Starter 100,000 · Growth 1,000,000 · Scale 10,000,000 | ทุกครั้งที่เรียก POST /v1/search และ POST /v1/similar ไม่ว่าแบบไหน |
ค้นด้วยความหมายFree 1,000 · Starter 30,000 · Growth 400,000 · Scale 4,000,000 | POST /v1/search ที่ได้ answered.by เป็น meaning ไม่ว่า mode ไหน และ POST /v1/similar ที่ได้ by เป็น meaning — นับเพิ่มจากการค้นหา · ครั้งที่ตอบด้วยคำ (auto ที่อ่านเป็นชื่อหรือรหัส หรือถูกลดเป็นคำ) ไม่นับ |
คำแนะนำFree 100,000 · Starter 1,000,000 · Growth 10,000,000 · Scale 100,000,000 | ทุกครั้งที่เรียก GET /v1/suggest รวมที่ขอ products มาด้วย |
จัดอันดับใหม่Free 0 · Starter 3,000 · Growth 50,000 · Scale 500,000 | POST /v1/search ที่ขอ rerank: "inline" |
ระเบียนที่ส่งเข้าดัชนีFree 40,000 · Starter 400,000 · Growth 4,000,000 · Scale 40,000,000 | ระเบียนที่ POST /v1/sync ส่งจริง (sent) — ระเบียนที่ส่งซ้ำโดยไม่เปลี่ยนไม่นับ |
สร้างเวกเตอร์ใหม่ทั้งชุดFree 1 · Starter 2 · Growth 6 · Scale 12 | เปิดการค้นด้วยความหมายอีกครั้งหลังปิด · ระเบียนที่ส่งมาหลังพร้อมแล้วไม่นับ |
ไม่นับ | POST /v1/filters, POST /v1/documents (นับตอน sync), GET ทุกเส้นที่อ่านการตั้งค่าหรือระเบียน และ PUT ทุกเส้นที่ตั้งค่า |
ลดทอน (degraded) ไม่ใช่ล้มเหลว
เมื่อโควตา vector ของเดือนนี้หมด หรือแพ็กเกจไม่รวมความสามารถที่ขอมา การค้นหา ไม่ ล้มเหลว — มันตอบด้วยการค้นด้วยคำตามปกติ แล้วแนบเหตุผลมาข้าง ๆ
{
"total": 12,
"hits": [ /* ... */ ],
"degraded": {
"asked": "hybrid",
"served": "keyword",
"reason": "quota_exhausted",
"message": "this month's vector searches are used up"
}
}คีย์ degraded มาพร้อมผลลัพธ์เสมอ ไม่ใช่แทนที่ผลลัพธ์ คนที่กำลังพิมพ์อยู่ที่กล่องค้นหาไม่ได้ขอเข้ามาคุยเรื่องค่าบริการ ฝั่งคุณจะเอาไปขึ้นป้ายหรือจะเก็บเข้าล็อกอย่างเดียวก็ได้
คำขอเดียวเสียได้มากกว่าหนึ่งอย่าง — ขอทั้ง knn และ rerank ตอนที่โควตาหมดทั้งคู่ จะถูกถอดออกทั้งคู่ ตัวที่แพงกว่าเป็นหัวเรื่อง ส่วนที่เหลืออยู่ใน also ถ้าฝั่งคุณแตกสาขาตาม reason ต้องอ่าน also ด้วย ไม่อย่างนั้นจะพลาดสิ่งที่หายไปเงียบ ๆ
{
"degraded": {
"asked": "vector",
"served": "keyword",
"reason": "quota_exhausted",
"message": "this month's 30,000 vector searches are used up",
"also": [
{
"asked": "rerank",
"served": "unreranked",
"reason": "not_on_plan",
"message": "reranks are not included in this plan"
}
]
}
}reason เป็นค่าคงที่ให้แตกสาขาได้ และ asked/served บอกว่าขออะไรได้อะไร (โหมด หรือตัวเลขสำหรับขนาดหน้า) ส่วน message เป็นประโยคให้คนอ่าน
| ฟิลด์ | ความหมาย |
|---|---|
quota_exhausted | โควตาของเดือนนี้หมด — ได้ผลแบบที่ถูกกว่าแทน |
not_on_plan | แพ็กเกจนี้ไม่รวมความสามารถนั้น (vector, rerank) |
not_enabled | ยังไม่ได้เปิดการค้นด้วยความหมายของชุดข้อมูลนี้ (PUT /v1/vectors) |
not_ready | เปิดแล้ว แต่โมเดลยังอ่านระเบียนไม่เสร็จ |
model_changed | เวกเตอร์ของชุดข้อมูลทำด้วยโมเดลอื่น ต้องสร้างใหม่ก่อน |
no_vector_supplied | ขอความหมายแต่ไม่มีข้อความให้แปลง (query ไม่ใช่สตริง) |
page_size_capped | size เกินเพดานต่อหน้าของชุดข้อมูล และมีผลถูกตัดจริง · asked/served เป็นตัวเลข |
window_capped | from + size เกินตำแหน่งสุดท้ายของเส้นทางนั้น (10,000 เมื่อค้นด้วยคำ, 1,000 เมื่อค้นด้วยความหมาย) — ไล่ต่อด้วย search_after |
pages_capped | ขอ pages ไกลกว่าที่เคอร์เซอร์ไปถึง (หน้าที่ตำแหน่งแรกไม่เกิน 10,000) — served คือหน้าสุดท้ายที่มีเคอร์เซอร์ ไล่ต่อจากหน้านั้นด้วย next |
no_page_cursors | ค้นด้วยความหมายไม่มีเคอร์เซอร์ของหน้า — ใส่เลขหน้าด้วย from ภายใน 1,000 |
facet_buckets_capped | ตัวกรองวันที่มีช่องที่มีสินค้าเกิน 200 ช่อง เพราะสินค้าเพิ่มหลังบันทึกขั้น — ได้ 200 ช่องล่าสุด สินค้าในช่องที่เก่ากว่านับรวมใน other ของตัวกรองนั้น · asked/served เป็นจำนวนช่อง |
not_loaded | ชุดข้อมูลยังไม่มีระเบียนที่ขึ้นดัชนี |
unreachable · no_endpoint · bad_reply | rerank แบบ inline ทำไม่สำเร็จ ผลยังเรียงตามคะแนนเดิม |
/v1/suggest ซึ่งถูกปฏิเสธด้วย 402 ตรง ๆ เพราะไม่มีอะไรให้ลดทอน (degraded) — รายการคำแนะนำที่ว่างเปล่าหน้าตาเหมือน ดรอปดาวน์ปกติ การบอกออกมาทำให้ฝั่งคุณหยุดยิงทุกการกดแป้นได้คำเตือน (warnings) — ตอบตามปกติ พร้อมเรื่องที่ควรแก้
คำเตือนไม่เปลี่ยนคำตอบ — สถานะและเนื้อเหมือนเดิมทุกอย่าง มีแค่สองที่ที่บอกเพิ่ม: warnings ในเนื้อ JSON สำหรับโปรแกรมที่อ่านคำตอบ และหัวข้อ NS-Warning ที่เห็นในแท็บ Network ของ devtools และ JavaScript ในหน้าเว็บอ่านได้
NS-Warning: service_key_in_browser: this request came from a web page with the dataset's service key, …
{ "total": 3, "hits": [ … ],
"warnings": [ { "reason": "service_key_in_browser", "message": "this request came from a web page …" } ] }| ฟิลด์ | ความหมาย |
|---|---|
service_key_in_browser | คำขอนี้ใช้ service key และมาจากหน้าเว็บ (มีหัวข้อ Origin) — ยังตอบตามปกติ แต่ service key แก้และลบชุดข้อมูลได้ และใครเปิดหน้านั้นก็อ่านคีย์ได้ · ในหน้าเว็บให้ใช้ client key ที่ค้นได้อย่างเดียว แล้วเพิ่มโดเมนของหน้าด้วย PUT /v1/origins · service key เก็บไว้ที่เซิร์ฟเวอร์ |
ใช้เกินเพดานได้ ถ้าเปิดไว้
โดยปกติเพดานคือกำแพง — ค้นหาจะลดทอน (degraded) เขียนจะได้ 402 ถ้าเปิดการใช้เกินไว้ เพดานจะกลายเป็นราคาแทน สำหรับมิเตอร์ที่ขายส่วนเกินได้ บัญชีจะทำงานต่อได้และส่วนที่เกินจะสะสมไว้ในยอดค้าง
ต้องครบสี่ข้อทุกครั้ง — แพ็กเกจต้องขายส่วนเกินของมิเตอร์นั้น บัญชีต้องเปิดไว้ บัญชีต้องตั้งงบไว้ และงบต้องยังเหลือ งบที่ยังไม่ได้ตั้ง คือไม่มีงบ ไม่ใช่ไม่จำกัด เพราะส่วนเกินที่ไม่มีเพดานคือวิธีที่ลูปหลุดกลายเป็นใบแจ้งหนี้ที่ไม่มีใครจ่าย
| ฟิลด์ | ความหมาย |
|---|---|
ค้นหา · vector · rerank · คำแนะนำ · เขียนระเบียนใช้เกินได้ | ถ้าแพ็กเกจขาย และบัญชีเปิดไว้พร้อมงบ |
สร้างเวกเตอร์ใหม่ทั้งชุดเป็นกำแพงเสมอ | ทั้งคลังผ่านโมเดลอีกรอบ คือ GPU หลายชั่วโมงต่อค่าบริการคงที่ |
คำขอต่อวินาทีเป็นกำแพงเสมอ | กันวินาทีถัดไป ไม่ใช่ยอดเดือน คำตอบคือ 429 ไม่ใช่ใบแจ้งหนี้ |
จำนวนชุดข้อมูล · คีย์ · ประวัติเป็นกำแพงเสมอ | เป็นความจุที่บัญชีมี ไม่ใช่สิ่งที่บัญชีใช้ไป |
ชนงบแล้วเกิดอะไร
402 เหมือนเดิม ไม่มีสถานะใหม่ให้รับมือ และแพ็กเกจฟรีเปิดการใช้เกินไม่ได้เลย เพราะไม่มีบัตรก็ไม่มีบิลเขียนซ้ำโดยไม่ให้เกิดสองครั้ง
ส่ง Idempotency-Key มากับคำขอที่เขียนข้อมูล แล้วคำขอเดิมที่ถูกส่งซ้ำจะได้คำตอบเดิมกลับไปโดยไม่ทำงานอีกรอบ — สำหรับตอนที่เครือข่ายหลุดแล้วคุณไม่รู้ว่าคำขอแรกถึงหรือเปล่า
Idempotency-Key: upload-2026-09-13-batch-4ยาวได้ไม่เกิน 255 ตัวอักษร · ใช้คีย์ใหม่ต่อการเขียนหนึ่งครั้ง ถ้าเอาคีย์เดิมไปใช้กับคำขอที่เนื้อหาต่างออกไปจะได้ 409 และคำขอที่ล้มเหลวไปแล้วจะไม่ถูกจำคำตอบไว้ ลองใหม่ได้ตามปกติ