คู่มืออ้างอิง Error Codes

ทุก Response ที่ไม่ใช่ 2xx จาก Ocriva API จะส่งคืน JSON error object ในรูปแบบที่สม่ำเสมอ หน้านี้รวบรวม Status Codes ทั้งหมด พร้อมสาเหตุและวิธีแก้ไข

รูปแบบ Error Response

API errors ทั้งหมดใช้ JSON envelope เดียวกัน:

{
  "statusCode": 400,
  "message": "Validation failed: templateId must be a non-empty string",
  "error": "Bad Request"
}

บาง Endpoint ที่คืนค่า Validation errors แบบรายฟิลด์จะขยาย message เป็น Array:

{
  "statusCode": 400,
  "message": [
    "templateId must be a non-empty string",
    "projectId must be a UUID"
  ],
  "error": "Bad Request"
}

ตารางอ้างอิงด่วน

400 Bad Request

คำขอมีรูปแบบไม่ถูกต้อง — ฟิลด์ที่จำเป็นขาดหาย ค่ามีประเภทข้อมูลผิด หรือ Parameter ไม่ผ่านการตรวจสอบรูปแบบ

สาเหตุที่พบบ่อย:

• ขาด templateId หรือ projectId ใน Upload request
• ส่ง pageRange เป็น String แทนที่จะเป็น Object
• ระบุ organizationId ที่ไม่ใช่ ObjectId ที่ถูกต้อง

ตัวอย่าง — ฟิลด์ที่จำเป็นขาดหาย:

POST /api/upload
{
  "projectId": "proj_abc123"
  # templateId omitted
}

Response:

{
  "statusCode": 400,
  "message": "Validation failed: templateId must be a non-empty string",
  "error": "Bad Request"
}

วิธีแก้ไข: ตรวจสอบ Request body เทียบกับ API Reference โดย Parameter ที่จำเป็นทุกตัวต้องมีครบและมีประเภทข้อมูลที่ถูกต้อง ดูฟิลด์ message — ระบุชื่อฟิลด์ที่ไม่ผ่านการตรวจสอบไว้ชัดเจน

401 Unauthorized

ไม่สามารถยืนยันตัวตนของคำขอได้ หมายความว่า API Key ขาดหาย มีรูปแบบไม่ถูกต้อง ถูกยกเลิก หรือไม่มีสิทธิ์เข้าถึง Resource ที่ร้องขอ

สาเหตุที่พบบ่อย:

• ไม่มี Header X-API-Key
• Token ถูกลบหรือถูกสร้างใหม่นับจากเวลาที่สร้าง Request
• ใช้ Token ระดับองค์กรกับ Project ที่สังกัดองค์กรอื่น

ตัวอย่าง:

GET /api/processing-history
# X-API-Key header missing

Response:

{
  "statusCode": 401,
  "message": "Invalid or missing API key",
  "error": "Unauthorized"
}

วิธีแก้ไข: ตรวจสอบให้แน่ใจว่าทุก Request มี Header X-API-Key พร้อม Token ที่ถูกต้อง Token สร้างได้ที่ Organization → API Tokens หรือ Project → API Tokens และจะแสดงค่าเต็มเพียงครั้งเดียวตอนสร้าง หาก Token สูญหาย ให้สร้างใหม่

403 Forbidden

API Key ถูกต้องแต่ไม่มีสิทธิ์ดำเนินการที่ร้องขอ

สาเหตุที่พบบ่อย:

• ใช้ Token ที่ผูกกับ Project หนึ่งเพื่อเข้าถึง Resource ของ Project อื่น
• IP ต้นทางขององค์กรไม่อยู่ใน Allowlist ของ Webhook endpoint
• พยายามดำเนินการระดับ Admin (เช่น ลบองค์กร) ด้วย Token ของสมาชิกทั่วไป

ตัวอย่าง:

DELETE /api/organizations/org_xyz
# Token belongs to a member role, not an owner

Response:

{
  "statusCode": 403,
  "message": "You do not have permission to delete this organization",
  "error": "Forbidden"
}

วิธีแก้ไข: ใช้ Token ที่มี Scope ที่จำเป็น สำหรับการดำเนินการระดับองค์กรให้ใช้ Organization Token จากบัญชี Owner สำหรับการแยก Project ให้ตรวจสอบว่า Project ของ Token ตรงกับ Resource ที่กำลัง Query

404 Not Found

ไม่พบ Resource ที่ร้องขอ หรือมีอยู่แต่สังกัด Project หรือองค์กรอื่นที่ไม่ตรงกับ Scope ของ Token

สาเหตุที่พบบ่อย:

• พิมพ์ Record ID ผิด (เช่น Prefix hist_ สำหรับ Processing history records)
• Query Resource ด้วย Token ที่ผูกกับ Project ขณะที่ Resource สังกัด Project อื่น
• Resource ถูกลบก่อนที่ Request จะมาถึง

ตัวอย่าง:

GET /api/processing-history/hist_does_not_exist?projectId=proj_abc123

Response:

{
  "statusCode": 404,
  "message": "Processing history record not found",
  "error": "Not Found"
}

วิธีแก้ไข: ตรวจสอบ ID จากหน้า Processing History ใน Dashboard หากใช้ API ให้ยืนยันว่า Query parameter projectId ตรงกับ Project ที่ Record นั้นสังกัดอยู่

409 Conflict

คำขอขัดแย้งกับข้อมูลที่มีอยู่ หรือกับ Operation ที่กำลังดำเนินการพร้อมกัน

สาเหตุที่พบบ่อย:

• สร้าง Template ที่มีชื่อซ้ำกับ Template ที่มีอยู่แล้วใน Project
• คำขอสองรายการที่ส่งพร้อมกันพยายามหักเครดิตจากยอดเดิม (Optimistic locking violation)

ตัวอย่าง — ชื่อ Template ซ้ำ:

{
  "statusCode": 409,
  "message": "A template named 'Invoice Extractor' already exists in this project",
  "error": "Conflict"
}

ตัวอย่าง — การอัปเดตเครดิตพร้อมกัน:

{
  "statusCode": 409,
  "message": "Credit was modified by another process. Please retry.",
  "error": "Conflict"
}

วิธีแก้ไข: สำหรับ Conflict จากชื่อซ้ำ ให้เลือกชื่อที่ไม่ซ้ำหรืออัปเดต Resource ที่มีอยู่ สำหรับ Conflict จาก Credit Concurrency ระบบจะ Retry อัตโนมัติสูงสุดสามครั้ง — หาก Error ยังคงเกิดขึ้นต่อเนื่อง ให้ลดจำนวน Processing request ที่ส่งพร้อมกัน หรือติดต่อ Support

413 Payload Too Large

ไฟล์ที่อัปโหลดเกินขีดจำกัดขนาดที่กำหนดสำหรับแพ็กเกจ Subscription ขององค์กร

Response:

{
  "statusCode": 413,
  "message": "File size exceeds the maximum allowed limit of 20 MB",
  "error": "Payload Too Large"
}

วิธีแก้ไข: บีบอัดหรือแบ่งไฟล์ก่อนอัปโหลด ดูขีดจำกัดต่อไฟล์ปัจจุบันได้ที่ Organization → Limits โดยทั่วไปแผนมาตรฐานรองรับไฟล์ไม่เกิน 20 MB การอัปเกรดแพ็กเกจจะเพิ่มขีดจำกัดนี้

429 Too Many Requests

API Key เกิน Rate Limit ในช่วงเวลาปัจจุบัน

Response:

{
  "statusCode": 429,
  "message": "Rate limit exceeded. Retry after 32 seconds.",
  "error": "Too Many Requests"
}

Response จะมี Header Retry-After ระบุจำนวนวินาทีที่ต้องรอ:

Retry-After: 32

วิธีแก้ไข: รอให้ Window รีเซ็ตก่อนส่ง Request เพิ่มเติม SDK จัดการสิ่งนี้โดยอัตโนมัติ — อ่าน Header Retry-After และหยุดรอก่อน Retry (สูงสุด maxRetries ครั้ง) สำหรับงานที่ต้องประมวลผลจำนวนมาก ให้ใช้ Endpoint Batch Processing เพื่อรวมหลายไฟล์เป็น API Call เดียว แทนการอัปโหลดทีละไฟล์

ดู SDK Error Handling — Rate Limiting สำหรับตัวเลือกการกำหนดค่า Retry

500 Internal Server Error

เกิดข้อผิดพลาดที่ไม่คาดคิดบน Server ซึ่งไม่ได้เกิดจากคำขอของคุณ

Response:

{
  "statusCode": 500,
  "message": "An unexpected error occurred. Please try again later.",
  "error": "Internal Server Error"
}

เมื่อไรควร Retry: Error 500 ที่เกิดชั่วคราว (เช่น ปัญหาฐานข้อมูลชั่วขณะ) มักหายไปเอง SDK จะ Retry อัตโนมัติสำหรับ Response 5xx ด้วย Exponential backoff

เมื่อไรควรติดต่อ Support: หาก Error เกิดซ้ำหลายครั้งหลัง Retry หรือคงอยู่นานหลายนาที ให้เปิด Support Ticket ที่ Support → Tickets โดยแนบข้อมูลต่อไปนี้:

• requestId หรือ eventId จาก Response headers (ดู เคล็ดลับการ Debug ด้านล่าง)
• Endpoint และ Request body (ปิดบัง Secrets)
• Timestamp ของ Request ที่ล้มเหลว

SDK Error Mapping

@ocriva/sdk แมป HTTP status codes กับ Error classes แบบ Typed เพื่อให้ใช้การตรวจสอบด้วย instanceof แทนการเปรียบเทียบตัวเลข Status ตรงๆ:

ดู SDK Error Handling สำหรับ Error hierarchy ทั้งหมด Property reference และตัวอย่างโค้ด

Webhook Error Codes

การส่ง Webhook และการตรวจสอบ Signature มีโหมดความล้มเหลวเฉพาะที่แสดงในส่วน Webhooks → Delivery Logs ของ Dashboard

ความล้มเหลวในการส่ง

Ocriva จะ Retry การส่งที่ล้มเหลวโดยอัตโนมัติ แต่ละครั้งที่ Retry จะถูกบันทึกพร้อมสถานะของตัวเอง หากการ Retry ทั้งหมดล้มเหลว Event จะถูกทำเครื่องหมายว่าล้มเหลวถาวร และคุณสามารถ Replay ด้วยตนเองจาก Delivery log

ความล้มเหลวในการตรวจสอบ Signature

หาก Endpoint ของคุณปฏิเสธ Header X-OCR-Signature ให้ตรวจสอบ:

1. คุณใช้ Signing secret ที่แสดงตอนสร้าง Endpoint (แสดงเพียงครั้งเดียว)
2. คุณคำนวณ HMAC-SHA256 จาก Raw request body bytes — ไม่ใช่ JSON string ที่ถูก Parse หรือ Re-serialize แล้ว
3. Header Content-Type บน Incoming request เป็น application/json

ดู Webhooks Guide สำหรับตัวอย่างโค้ดการตรวจสอบแบบเต็ม

เคล็ดลับการ Debug

ใช้ requestId และ eventId

ทุก API Response มี Header requestId ทุก Webhook payload มีฟิลด์ eventId ใส่ตัวระบุเหล่านี้เมื่อเปิด Support ticket — ช่วยให้ทีม Ocriva ติดตาม Request นั้นผ่าน Server logs ได้อย่างแม่นยำ

# Extract requestId from a curl response
curl -si https://api.ocriva.com/api/processing-history \
  -H "X-API-Key: $OCRIVA_API_KEY" \
  | grep -i x-request-id

ตรวจสอบ Processing History

หน้า Processing History บันทึกผลลัพธ์ของทุกเอกสาร รวมถึงความล้มเหลว คลิกที่ Record ใดก็ได้เพื่อขยายดูข้อความ Error ที่แน่ชัดที่คืนมาจาก AI provider หรือ Internal processing pipeline ใช้ตัวกรอง ID เพื่อไปยัง Record เฉพาะโดยตรงด้วย ID ที่มี Prefix hist_

ลองทำ Request แบบเรียบง่ายที่สุด

ตัด Request ของคุณให้เหลือเฉพาะฟิลด์ที่จำเป็นขั้นต่ำ แล้วเพิ่มฟิลด์กลับทีละตัว วิธีนี้ช่วยระบุว่า Parameter ใดที่ทำให้เกิด Validation error 400

ดูคู่มือที่เกี่ยวข้อง

• คำถามที่พบบ่อยและการแก้ไขปัญหา — สถานการณ์ Error ที่พบบ่อยพร้อมวิธีแก้ไขแบบทีละขั้นตอน
• SDK Error Handling — Typed errors, การ Retry อัตโนมัติ และ Rate limit backoff
• Webhooks Guide — การ Retry การส่งและการตรวจสอบ Signature