การจัดการ Error

SDK มี typed error class ที่จัดเรียงเป็น hierarchy เพื่อให้คุณจัดการความล้มเหลวของ API ได้อย่างแม่นยำด้วยการตรวจสอบ instanceof นอกจากนี้ SDK ยัง retry ความล้มเหลวชั่วคราวโดยอัตโนมัติ ช่วยลด edge case ที่คุณต้องจัดการเอง

Error Hierarchy

SDK error ทั้งหมด extend มาจาก base class OcrivaError:

OcrivaError           ← base class for all SDK errors
└── ApiError          ← non-2xx HTTP responses (has statusCode, error)
    ├── AuthenticationError  ← 401 Unauthorized
    ├── RateLimitError       ← 429 Too Many Requests (has retryAfter)
    └── NotFoundError        ← 404 Not Found

base class OcrivaError ยังถูก throw โดยตรงสำหรับ configuration error (เช่น API key หายไป, baseUrl ไม่ถูกต้อง) และความล้มเหลวระดับ network (เช่น timeout, DNS failure)

การดักจับ Error

Import error class พร้อมกับ client:

import {
  OcrivaClient,
  OcrivaError,
  ApiError,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
} from '@ocriva/sdk';
 
const client = new OcrivaClient({ apiKey: process.env.OCRIVA_API_KEY! });
 
try {
  const record = await client.processingHistory.get('hist_abc123', 'proj_abc123');
  console.log(record.status);
} catch (error) {
  if (error instanceof AuthenticationError) {
    // 401 — API key is invalid, expired, or does not have access to this resource
    console.error('Authentication failed. Check your API key.');
  } else if (error instanceof RateLimitError) {
    // 429 — too many requests; the SDK already retried maxRetries times
    console.error(`Rate limited. Retry after ${error.retryAfter ?? 'unknown'} seconds.`);
  } else if (error instanceof NotFoundError) {
    // 404 — the requested resource does not exist
    console.error('Record not found:', error.message);
  } else if (error instanceof ApiError) {
    // Any other non-2xx response (400, 403, 500, etc.)
    console.error(`API error ${error.statusCode}: ${error.message}`);
  } else if (error instanceof OcrivaError) {
    // Network timeout, invalid config, or unknown SDK error
    console.error('SDK error:', error.message);
  } else {
    // Unexpected non-SDK error
    throw error;
  }
}

Error Properties

OcrivaError

ApiError

Extends OcrivaError.

RateLimitError

Extends ApiError.

} catch (error) {
  if (error instanceof RateLimitError && error.retryAfter !== undefined) {
    // Manually wait and retry if you have disabled automatic retries
    await new Promise((resolve) => setTimeout(resolve, error.retryAfter! * 1000));
  }
}

การ Retry อัตโนมัติ

SDK retry request ที่ล้มเหลวโดยอัตโนมัติเมื่อ server ส่ง response 429 หรือ 5xx การ retry ใช้ exponential backoff ด้วยฐาน 1 วินาที และ cap 30 วินาที:

สำหรับ response 429 SDK จะใช้ header Retry-After จาก server แทน backoff หากมี

จำนวนครั้งในการ retry ควบคุมด้วย option maxRetries (ค่าเริ่มต้น: 3) ตั้งเป็น 0 เพื่อปิดการ retry อัตโนมัติทั้งหมด:

const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_API_KEY!,
  maxRetries: 0, // disable automatic retries
});

เมื่อ retry ครบทุกครั้งแล้ว SDK จะ throw error ที่เกี่ยวข้อง (RateLimitError สำหรับ 429, ApiError สำหรับ 5xx)

Rate Limiting

Ocriva API อนุญาต 60 request ต่อนาที ต่อ API key หากเกินขีดจำกัดนี้ API จะส่ง 429 Too Many Requests

ในส่วนใหญ่ SDK จัดการเรื่องนี้อย่างโปร่งใส — หยุดชั่วคราวและ retry จนกว่า rate limit window จะ reset หาก retry หมดแล้วหรือคุณปิดการ retry จะมีการ throw RateLimitError

เพื่อหลีกเลี่ยงการกระทบ rate limit ในการทำงานแบบ bulk ลองพิจารณา:

• ใช้ batch resource เพื่อรวมไฟล์หลายไฟล์เป็น API call เดียวแทนการอัปโหลดทีละไฟล์
• เพิ่มหน่วงเวลาระหว่าง request ในลูปที่ทำงานถี่

สำหรับกลยุทธ์ rate limiting ขั้นสูงรวมถึงการ implement manual backoff ดูที่ Retry & Rate Limiting

Request Timeout

แต่ละ request มี timeout ที่ตั้งค่าได้ (ค่าเริ่มต้น: 30,000 ms) หาก request เกิน timeout SDK จะ throw OcrivaError พร้อมข้อความเช่น Request timed out after 30000ms

const client = new OcrivaClient({
  apiKey: process.env.OCRIVA_API_KEY!,
  timeout: 60_000, // increase to 60 s for large file uploads
});

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

เปิดใช้งาน verbose logging

เมื่อ error วินิจฉัยได้ยาก ให้ log property ทั้งหมดที่มีก่อนปล่อยให้ error propagate ต่อไป:

try {
  const result = await client.upload.create({ ... });
} catch (error) {
  if (error instanceof ApiError) {
    console.error('Status:', error.statusCode);
    console.error('Message:', error.message);
    console.error('Error:', error.error);
  }
  // For network errors, log the full error
  console.error('Full error:', error);
}

ตรวจสอบ Processing History

หลังจาก upload หากผลลัพธ์ดูไม่ถูกต้อง (extraction ว่างเปล่า, field ผิด) ให้ดึง processing record โดยตรงเพื่อตรวจสอบ status โดยละเอียดและข้อความ error ฝั่ง server:

const record = await client.processingHistory.get(result.historyId, 'proj_abc123');
console.log('Status:', record.status);
console.log('Error:', record.errorMessage);

ตรวจสอบ scope ของ API key

สาเหตุที่พบบ่อยของ error 401 และ 403 คือการใช้ organization-level API token กับ endpoint ที่กำหนดขอบเขตเป็น project หรือในทางกลับกัน เปิด Organization → API Tokens ใน dashboard และตรวจสอบว่าประเภท token ตรงกับ resource ที่คุณเรียกใช้

ทดสอบด้วย payload ขนาดเล็กก่อน

ก่อนรัน batch job ให้ทดสอบ template และ model configuration เดียวกันกับเอกสารชิ้นเดียวก่อน วิธีนี้ช่วยพบ template misconfiguration และ provider error ได้ตั้งแต่เนิ่นๆ ในต้นทุนที่ต่ำ

อ้างอิง Error ที่พบบ่อย

สำหรับแคตตาล็อก error code ที่ครอบคลุมพร้อมวิธีแก้ปัญหาโดยละเอียด ดูที่ Error Code Reference