오류

박스히어로 API가 반환하는 오류 응답 형식과 코드에서 오류를 처리하는 방법을 안내합니다.

요청이 실패하면 박스히어로 API는 HTTP 오류 상태 코드와 함께 아래 형식의 JSON 오류 응답을 반환합니다.

{
  "id": "ex_8f5c0c8e0e0a4a3c9b3f4f2c4f6c8d2a",
  "type": "/errors/not-found",
  "title": "No item with id 12345 found in this team.",
  "correlationID": "rq_01abf3c2b8e44a59be2a9c0f1e7d6a40",
  "instance": "/items/12345"
}

필드

필드	설명
`id`	오류의 고유 ID로, `ex_` 뒤에 16진수 소문자 32자가 붙습니다. 고객센터에 문의할 때 함께 알려 주세요.
`type`	변하지 않는 오류 코드입니다. 코드에서는 `title`이 아니라 이 값으로 분기해 주세요.
`title`	사람이 읽을 수 있는 영문 요약입니다. 문구는 바뀔 수 있습니다.
`correlationID`	요청 ID로, `rq_` 뒤에 16진수 소문자 32자가 붙으며 `X-Correlation-Id` 응답 헤더와 같은 값입니다. 로그에서 해당 요청을 찾을 때 사용합니다.
`instance`	오류가 발생한 자원입니다(예: `/items/12345`). 경로에 `/v1`은 붙지 않습니다.
`code`	오류의 세부 사유입니다(예: `tx-modify-revision-mismatch`). 없을 수도 있습니다. 먼저 `type`으로 분기한 뒤, 더 세밀하게 처리할 때 `code`를 사용해 주세요.
`errors`	필드별 오류 정보로, `/errors/invalid-request`(`400`) 응답에 포함됩니다. 각 항목에는 잘못된 필드의 위치를 나타내는 `path`와 사람이 읽을 수 있는 `message`가 있습니다.

일부 오류에는 관련 자원의 id(예: item_id, order_id)가 최상위 필드로 추가됩니다.

주요 상태 코드

상태 코드	의미	해결 방법
`400`	요청이 올바르지 않거나, 팀의 모드에서 지원하지 않는 엔드포인트	요청을 수정해 주세요. 잘못된 필드는 `errors`에서 확인할 수 있습니다. 같은 요청을 그대로 다시 보내지 마세요.
`401`	API 토큰이 없거나 유효하지 않음	`Authorization` 헤더를 확인해 주세요. 인증을 참고해 주세요.
`403`	박스히어로가 변경을 거부함(예: 재고 규칙에 어긋나거나 보낸 `revision`이 최신이 아님)	`code`에서 이유를 확인한 뒤, 요청을 수정하거나 최신 데이터를 다시 조회해 재시도해 주세요.
`404`	팀에 해당 자원이 없거나 삭제됨	id를 확인해 주세요. 같은 요청을 그대로 다시 보내지 마세요.
`429`	요청이 너무 많음	잠시 기다린 후 다시 시도해 주세요. 호출 제한을 참고해 주세요.

엔드포인트별로 반환할 수 있는 오류 유형은 API 레퍼런스에서 확인할 수 있습니다.

revision 충돌 처리

입출고 내역을 수정하거나 삭제하려면 마지막으로 확인한 revision을 함께 보내 주세요. 그사이 다른 사람이 내역을 변경했다면 revision이 맞지 않아 요청이 403으로 거부되며, code가 tx-modify-revision-mismatch로 반환됩니다. code로 분기해 내역을 다시 조회하고 변경 사항을 확인한 뒤, 새 revision으로 다시 시도해 주세요.

const res = await fetch(`https://rest.boxhero-app.com/v1/transactions/${id}`, {
  method: "PUT",
  headers: {
    Authorization: `Bearer ${process.env.BOXHERO_API_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ revision, memo: "재고 재확인" }),
});

if (res.status === 403) {
  const error = await res.json();
  if (error.code === "tx-modify-revision-mismatch") {
    // 내역을 다시 조회해 변경 사항을 확인한 뒤, 새 revision으로 다시 시도합니다.
  }
}