API Reference

Errors

ใช้ HTTP status สำหรับชั้นขนส่ง และฟิลด์ code ใน body สำหรับจัดการในโปรแกรม อย่าแยก logic จาก title หรือ detail

Key Extraction v3 — problem+json

Content-Type application/problem+json ตาม RFC 9457

json
{
"type": "https://docs.aksonocr.com/problems/invalid-schema",
"title": "Invalid Schema",
"status": 422,
"code": "invalid_schema",
"detail": "The schema contains unsupported constructs.",
"instance": "urn:aksonocr:request:req_01JBY8...",
"retryable": false,
"errors": [
{
"pointer": "/properties/items/items",
"code": "nested_array_not_supported",
"detail": "Nested arrays are not supported."
}
],
"request_id": "req_01JBY8..."
}
ฟิลด์ใช้ทำอะไร
statusHTTP เดียวกันกับชั้นขนส่ง
codeสาขาในโปรแกรม (เสถียร)
retryabletrue เมื่อควรลองใหม่
errors[]รายการย่อยพร้อม JSON Pointer
request_idส่งให้ซัพพอร์ตเมื่อไล่บั๊ก

รหัสของ Key Extraction v3

HTTPcodeRetryความหมาย
400invalid_request, input_conflictไม่ฟิลด์หรือไฟล์ไม่ถูกต้อง รวมถึงฟิลด์ที่ไม่รู้จักใน body
401invalid_api_keyไม่ไม่มีหรือ API key ไม่ถูกต้อง
404job_not_found, file_not_found, template_not_foundไม่ไม่พบหรือไม่มีสิทธิ์
409result_not_ready, file_in_use, idempotency_conflict, already_terminal, template_archivedไม่*ชนสถานะ resource
410result_expired, file_expiredไม่เลย retention
413payload_too_large, page_limit_exceededไม่ไฟล์หรือหน้าเกินลิมิต
415unsupported_media_typeไม่ชนิดไฟล์ไม่รองรับ
422invalid_schema, unreadable_documentไม่schema หรือเอกสารอ่านไม่ได้
429rate_limitedใช่เกินโควตาต่อบัญชี — รอให้งานเดิมจบแล้วลองใหม่
503temporarily_unavailableใช่คิวไม่พร้อมชั่วคราว — backoff แล้วลองใหม่
* result_not_ready ให้ poll ต่อ ไม่ใช่เปลี่ยน request

OCR v2 / v3 body

OCR ไม่ใช้ problem+json — error.code มักเป็น HTTP_ERROR ทุกกรณี ให้แยกด้วย HTTP status และอ่าน error.message เพื่อดูรายละเอียด

json
{
"success": false,
"error": {
"code": "HTTP_ERROR",
"message": "Invalid model: bogus. Use one of the available models."
},
"timestamp": "2026-11-17T09:48:54.877Z",
"path": "/api/v3/ocr",
"method": "POST"
}
HTTPOCR v2 / v3
400ฟิลด์ผิด เช่น ไม่ส่ง model หรือ action, ชนิดไฟล์ไม่รองรับ
401ไม่มีหรือ API key ไม่ถูกต้อง
402เครดิตไม่พอ
404ไม่พบงาน OCR v3
429เกิน RPM หรือโควตาต่อวันของโมเดล
504OCR v2 ประมวลผลไม่ทันเวลา — เอกสารยาวให้ใช้ OCR v3

OCR v3 job ที่ล้มเหลวหลังรับงานแล้ว จะมีสถานะ failed และข้อความ error ในตัวงาน

เมื่อไหร่ควร retry

  • 429 / 503 — exponential backoff + jitter ถ้ามี Retry-After ให้รอตามนั้น
  • สร้างงาน v3 — ใช้ Idempotency-Key เดิมเมื่อ retry
  • อย่า retry 400, 401, 402, 404, 410, 413, 415, 422 ด้วย payload เดิม
Error จะไม่มี stack trace, ข้อความเอกสาร, API key หรือ path ใน object storage