오류 처리

표준 오류 코드로 오류를 적절히 처리하세요.

오류 응답 형식

모든 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 키가 유효하지 않거나 만료되었거나 취소되었습니다.
`402`	`quota_exceeded`	월간 요청 쿼터를 초과했습니다. 플랜을 업그레이드하세요.
`422`	`invalid_image`	image 필드가 없거나 유효하지 않은 base64이거나 5MB를 초과합니다.
`422`	`invalid_request`	요청 본문이 유효한 JSON이 아닙니다.
`502`	`inference_error`	ML 추론 서비스를 일시적으로 사용할 수 없습니다. 백오프로 재시도하세요.

오류 응답 예시

API 키 누락 (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 상태 코드를 확인하세요.
502 오류에 대해 지수 백오프를 구현하세요.
응답 헤더를 통해 쿼터 사용량을 모니터링하세요.
401이나 422 오류는 재시도하지 마세요.
프로그래밍 방식의 오류 처리에는 메시지가 아닌 error.code 필드를 사용하세요.

재시도 예시

일시적 오류에 대한 지수 백오프 JavaScript 예시:

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");
}