AI Gridเอกสาร
สมัครใช้งาน

ข้อผิดพลาด

Error envelope และทุกรหัสที่ควรใช้แยกเงื่อนไขในโค้ด

อัปเดต 9 ก.ย. 2026

ข้อผิดพลาดส่งกลับมาใน JSON envelope:

json
{
  "error": {
    "code": "insufficient_budget",
    "message": "Top up this Project wallet before making a call",
    "requestId": "req_…"
  }
}

ทุกการตอบกลับของ /v1 เป็น JSON รวมถึง 404 และ 5xx ไม่มีหน้า HTML error อยู่หลัง prefix นี้

Credentials — 401#

Code ความหมาย
invalid_api_key ไม่มี bearer token หรือคีย์ไม่รู้จัก หมดอายุ หรือถูกเพิกถอน

เป็นผลลัพธ์สุดท้ายของคำขอนั้น การ retry ด้วยคีย์เดิมไม่ช่วย (console API ที่ใช้ session ตอบ 401 unauthenticated หาก cookie ไม่มีหรือถูกเพิกถอน แต่ bearer surface ตอบ invalid_api_key เสมอ)

Money — 402#

Code ความหมาย สิ่งที่แก้ได้
insufficient_budget กระเป๋าเงินของโปรเจกต์ครอบคลุมยอดที่กันไว้ไม่ได้ Owner เติมเงินให้โปรเจกต์

Access and policy — 403#

Code ความหมาย สิ่งที่แก้ได้
project_mismatch selector ระบุโปรเจกต์อื่นจากที่คีย์ผูกไว้ เอา selector ออก หรือระบุซ้ำโปรเจกต์ที่ผูกไว้
key_scope resource ใช้ได้ แต่ถูกตัดออกจาก allowlist ของคีย์ ใช้คีย์ที่ policy อนุญาต resource นั้น
key_unbound คีย์เก่าที่ไม่มีโปรเจกต์ผูกไว้ ออกคีย์ใหม่ที่ผูกกับโปรเจกต์
key_issuer_denied คุณออกคีย์สำหรับโปรเจกต์นี้ไม่ได้ (ขณะสร้างคีย์) กฎสมาชิกภาพ + team grant + project grant ใน การยืนยันตัวตน
product_not_assigned ผลิตภัณฑ์เรียกได้ในองค์กร แต่ยังไม่กำหนดให้โปรเจกต์นี้ ผู้ดูแลกำหนด assignment
policy_denied invocation policy ปฏิเสธโมเดลหรือขนาด output เจ้าของ policy
budget_limit ถึงเพดาน spending รายวัน/เดือนของ invocation policy รอรอบใหม่ หรือ Owner เพิ่มเพดาน
key_limit ใช้วงเงินของคีย์หมดแล้ว รอ reset window ของคีย์
denied ผู้เรียกไม่มี consumption authority — ไม่มี project grant หรือสมาชิกภาพ/องค์กร/โปรเจกต์ถูก suspend คืน grant หรือยกเลิก suspension

การเรียกที่ถูกปฏิเสธไม่สร้าง usage record และไม่กันเงิน

Not found — 404#

Code ความหมาย
model_not_found ไม่มี resource ที่มี id นี้และใช้ได้กับผู้เรียกในขณะนี้ — id ที่เดา, draft, deployment ที่ suspend, assignment ที่ถูกลบ หรือ resource ของโปรเจกต์อื่น
not_found object ที่ระบุ (key, sandbox product, project…) ไม่มีอยู่ใน scope ของผู้เรียก

404 สำหรับสิ่งที่มีอยู่ที่อื่นเป็นเจตนา: การเข้าถึงข้ามโปรเจกต์และข้ามองค์กรถูกปกปิด ไม่ถูกแยกให้รู้

Conflict — 409#

Code ความหมาย
revision_not_active external invocation รัน sandbox revision ที่ deploy อยู่ ให้ละ revision หรือ activate revision นั้น
revision_conflict baseRevision ของการบันทึก sandbox เก่า มีคนบันทึกก่อน ให้ reload ก่อนบันทึก
state record อยู่ใน state ที่ไม่ถูกต้องสำหรับ action เช่น หมุนคีย์ที่ไม่ active หรือแก้ sandbox product ที่ archived
key_unbound คีย์เก่าที่ไม่ผูกโปรเจกต์หมุนเวียนไม่ได้

Request shape — 422#

Code ความหมาย
unsupported_parameter ฟิลด์ไม่รู้จัก หรือฟิลด์ที่รู้จักแต่เกินขอบเขต — ดู การเติมข้อความในแชต
project_required การเรียกหรือการสร้างคีย์ไม่ระบุโปรเจกต์ในกรณีที่ต้องระบุ
sandbox_contract id ของ sandbox ใน model มี contract ที่ไม่ใช่ข้อความเข้าหนึ่ง/ข้อความออกหนึ่ง — ใช้ /v1/sandbox/{id}/invoke
resource_not_eligible รายการใน key allowlist ไม่ใช่ resource ที่โปรเจกต์ผูกไว้ใช้ได้
invalid ค่าไม่ถูกต้อง เช่น message role ผิด, tool message ไม่มี tool_call_id, หรือ temperature เกินช่วง
context_limit คำขอเกิน context หรือ output limit ที่โมเดลเผยแพร่
media_endpoint ส่ง media-only product ไปยัง chat completions — ให้เรียกผ่าน sandbox media node

การปฏิเสธ 4xx ทั้งหมดเกิด ก่อนกันเงิน จึงไม่ถูกคิดค่าใช้จ่าย (body ที่ไม่ใช่ JSON document ที่ถูกต้องถูกปฏิเสธก่อนหน้านั้นด้วย 400 invalid_body)

Rate limit — 429#

มีรหัสเดียวคือ rate_limit — 30 คำขอต่อนาทีต่อผู้เรียกภายในองค์กร window ยาวหนึ่งนาที ดู การจำกัดอัตราคำขอ

Upstream and internal — 5xx#

Status Code ความหมาย
502 provider_failed ผู้ให้บริการปฏิเสธอย่างชัดเจน — ยอดที่กันไว้ ถูกปล่อยคืน
502 provider_reconciling ผลลัพธ์ไม่แน่ชัด (timeout, คำตอบไม่สมบูรณ์, ไม่ทราบการรับคำขอ) — ยอดที่กันไว้ ถูกถือไว้ เพื่อ reconciliation
502 invalid_response ผู้ให้บริการไม่ส่ง completion ที่ใช้ได้
503 authority_unavailable ตรวจ authority ไม่สำเร็จ — ไม่มีการ dispatch
504 timeout เกิน deadline ของคำขอ

ระหว่างสตรีม ความล้มเหลวเดียวกันมาเป็น data: frame แทน โดยใช้รหัส provider_failed, provider_reconciling หรือ settlement_pending และมี invocation id เป็น id

อย่า retry 5xx แบบสร้างคำขอใหม่โดยไม่ตรวจสอบ คำขอที่ timeout หรือไม่แน่ชัดอาจยังมียอดที่กันไว้ หรือผู้ให้บริการอาจทำงานสำเร็จแล้ว ใช้ invocation id ตรวจผลที่บันทึกก่อน การ replay ด้วย Idempotency-Key เดิมปลอดภัยและไม่คิดเงินซ้ำ ไม่มี automatic paid retry

สิ่งที่ไม่ถึงผู้ให้บริการไม่ถูกคิดเงิน#

credential failure, access refusal, policy stop, validation error และกระเป๋าเงินว่างเกิดก่อน reservation หรือ dispatch จึงไม่เปลี่ยนยอด ผู้ให้บริการที่ปฏิเสธอย่างชัดเจนจะปล่อย reservation คืน มีเพียงผลลัพธ์ไม่แน่ชัดที่ถือไว้ และจะแสดงใน การใช้งาน จน reconciliation เสร็จ