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..."}
| ฟิลด์ | ใช้ทำอะไร |
|---|---|
status | HTTP เดียวกันกับชั้นขนส่ง |
code | สาขาในโปรแกรม (เสถียร) |
retryable | true เมื่อควรลองใหม่ |
errors[] | รายการย่อยพร้อม JSON Pointer |
request_id | ส่งให้ซัพพอร์ตเมื่อไล่บั๊ก |
รหัสของ Key Extraction v3
| HTTP | code | Retry | ความหมาย |
|---|---|---|---|
| 400 | invalid_request, input_conflict | ไม่ | ฟิลด์หรือไฟล์ไม่ถูกต้อง รวมถึงฟิลด์ที่ไม่รู้จักใน body |
| 401 | invalid_api_key | ไม่ | ไม่มีหรือ API key ไม่ถูกต้อง |
| 404 | job_not_found, file_not_found, template_not_found | ไม่ | ไม่พบหรือไม่มีสิทธิ์ |
| 409 | result_not_ready, file_in_use, idempotency_conflict, already_terminal, template_archived | ไม่* | ชนสถานะ resource |
| 410 | result_expired, file_expired | ไม่ | เลย retention |
| 413 | payload_too_large, page_limit_exceeded | ไม่ | ไฟล์หรือหน้าเกินลิมิต |
| 415 | unsupported_media_type | ไม่ | ชนิดไฟล์ไม่รองรับ |
| 422 | invalid_schema, unreadable_document | ไม่ | schema หรือเอกสารอ่านไม่ได้ |
| 429 | rate_limited | ใช่ | เกินโควตาต่อบัญชี — รอให้งานเดิมจบแล้วลองใหม่ |
| 503 | temporarily_unavailable | ใช่ | คิวไม่พร้อมชั่วคราว — backoff แล้วลองใหม่ |
*
result_not_ready ให้ poll ต่อ ไม่ใช่เปลี่ยน requestOCR 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"}
| HTTP | OCR v2 / v3 |
|---|---|
| 400 | ฟิลด์ผิด เช่น ไม่ส่ง model หรือ action, ชนิดไฟล์ไม่รองรับ |
| 401 | ไม่มีหรือ API key ไม่ถูกต้อง |
| 402 | เครดิตไม่พอ |
| 404 | ไม่พบงาน OCR v3 |
| 429 | เกิน RPM หรือโควตาต่อวันของโมเดล |
| 504 | OCR 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