에러 코드

페이싱크 v2 API 응답의 숫자 code 값마다 HTTP 상태와 발생 조건을 정리했어요.

v2 API 응답의 code는 처리 결과를 나타내는 숫자 문자열이에요. 앞자리로 분류를 알 수 있어요. 예를 들어 22로 시작하는 여섯 자리 코드는 주문, 24로 시작하는 코드는 현금영수증 오류예요.

{
  "code": "220003"
}

분기 처리는 HTTP 상태가 아니라 code로 하세요. 같은 HTTP 상태에도 여러 코드가 있어요. 엔드포인트별로 나올 수 있는 코드는 각 API 페이지에도 적혀 있어요. v1 API의 문자열 코드는 v1 에러 코드를 참고하세요.

성공

인증과 권한

공통 검증

리소스 없음 (404)

다른 워크스페이스의 리소스도 없는 것으로 보고 404가 와요.

주문

입금

현금영수증

서버 오류 (5xx)

예상하지 못한 서버 오류는 code 없이 본문이 빈 500으로 올 수 있어요. 응답 본문이 JSON이 아니어도 처리할 수 있게 만들어 주세요.

처리 예시

const res = await fetch(url, options);
const body = await res.json().catch(() => ({ code: null }));

switch (body.code) {
  case "10001":
    return body.data ?? body.items;

  case "290006":
    throw new Error("API 키를 확인하세요.");

  case "220010":
    // 같은 입금자명과 금액의 주문이 이미 있어요.
    return { duplicateOf: body.data.invoiceId };

  case "220002":
  case "220003":
  case "220004":
  case "220005":
    throw new ValidationError(body.code);

  default:
    if (res.status >= 500) return retryLater();
    // 새로 추가된 코드일 수 있어요. 기록하고 일반 오류로 처리하세요.
    logger.warn({ code: body.code, status: res.status }, "unknown PaySync code");
    throw new Error(`PaySync error: ${body.code}`);
}