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": "Schema is invalid",
  "status": 422,
  "code": "invalid_schema",
  "detail": "The schema contains unsupported constructs.",
  "instance": "urn:aksonocr:request:req_01JBY8...",
  "retryable": false,
  "errors": [
    {
      "pointer": "/data_schema/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`	ส่งให้ซัพพอร์ตเมื่อไล่บั๊ก

รหัสที่ใช้บ่อย

HTTP	code	Retry	ความหมาย
400	`invalid_request, unknown_property, input_conflict`	ไม่	ฟิลด์ ไฟล์ หรือ URL ไม่ถูกต้อง
401	`invalid_api_key / unauthorized`	ไม่	ไม่มีหรือ API key ไม่ถูกต้อง
402	`insufficient_credits`	ไม่	เครดิตไม่พอ
403	`forbidden`	ไม่	คีย์นี้ไม่มีสิทธิ์
404	`job_not_found, file_not_found, template_not_found`	ไม่	ไม่พบหรือไม่มีสิทธิ์
409	`result_not_ready, file_in_use, idempotency_conflict, already_terminal`	ไม่*	ชนสถานะ 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`	ใช่	เคารพ Retry-After
503	`temporarily_unavailable, queue_full, service_busy`	ใช่	เคารพ Retry-After

* result_not_ready ให้ poll ต่อ ไม่ใช่เปลี่ยน request

OCR v2 body

มักเป็น { "error": "...", "code": "..." }OCR v3 job ที่ล้มเหลวใส่ 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

Full Page OCR

Rate Limits