การจัดการข้อผิดพลาด

จัดการข้อผิดพลาดอย่างสง่างามด้วยรหัสข้อผิดพลาดมาตรฐาน

รูปแบบการตอบกลับข้อผิดพลาด

ข้อผิดพลาด API ทั้งหมดมีรูปแบบ JSON ที่สอดคล้องกัน

{
  "error": {
    "code": "error_code_here",
    "message": "A human-readable description of the error."
  }
}

รหัสข้อผิดพลาด

สถานะ	รหัส	คำอธิบาย
`401`	`missing_api_key`	ไม่มีส่วนหัว X-API-Key ในคำขอ
`401`	`invalid_api_key`	API key ที่ให้ไม่ถูกต้อง หมดอายุ หรือถูกเพิกถอน
`402`	`quota_exceeded`	โควตาคำขอรายเดือนเกินแล้ว อัปเกรดแผน
`422`	`invalid_image`	ฟิลด์ image หายไป ไม่ใช่ base64 ที่ถูกต้อง หรือเกิน 5MB
`422`	`invalid_request`	เนื้อหาคำขอไม่ใช่ JSON ที่ถูกต้อง
`502`	`inference_error`	บริการ ML ไม่พร้อมใช้งานชั่วคราว ลองใหม่ด้วย backoff

ตัวอย่างการตอบกลับข้อผิดพลาด

ไม่มี API Key (401)

{
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Include your key in the X-API-Key header."
  }
}

ภาพไม่ถูกต้อง (422)

{
  "error": {
    "code": "invalid_image",
    "message": "Image exceeds the maximum size of 5 MB."
  }
}

ข้อผิดพลาดการอนุมาน (502)

{
  "error": {
    "code": "inference_error",
    "message": "ML inference service is temporarily unavailable. Please retry."
  }
}

แนวทางปฏิบัติที่ดี

ตรวจสอบรหัสสถานะ HTTP ก่อนแยกวิเคราะห์เนื้อหาเสมอ
ใช้ exponential backoff สำหรับข้อผิดพลาด 502
ตรวจสอบการใช้โควตาผ่านส่วนหัวการตอบกลับ
อย่าลองใหม่สำหรับข้อผิดพลาด 401 หรือ 422
ใช้ฟิลด์ error.code สำหรับการจัดการข้อผิดพลาดแบบโปรแกรม

ตัวอย่างการลองใหม่

ตัวอย่าง JavaScript พร้อม exponential backoff:

async function analyzePalm(imageBase64, apiKey, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(
      "https://api.trace-line.site/v1/palm/analyze",
      {
        method: "POST",
        headers: {
          "X-API-Key": apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ image: imageBase64 }),
      }
    );

    if (res.ok) return res.json();

    const error = await res.json();

    // Only retry on transient errors
    if (res.status !== 502) throw error;

    // Exponential backoff: 1s, 2s, 4s
    await new Promise((r) =>
      setTimeout(r, 1000 * Math.pow(2, attempt))
    );
  }

  throw new Error("Max retries exceeded");
}