> For the complete documentation index, see [llms.txt](https://www.boxhero.io/docs/llms.txt). Every page is available as Markdown by appending `.md` to its URL; this page is [Markdown](https://www.boxhero.io/docs/ko/developers/api/errors.md).

# 오류

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

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

```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`)가 최상위 필드로 추가됩니다.

> **Note**
>
> 요청에 직접 만든 `X-Correlation-Id` 헤더를 넣으면 사용 중인 시스템의 추적 정보와 박스히어로의 로그를 연결할 수 있습니다. 같은 값이 응답 헤더와 `correlationID`로 돌아옵니다.

## 주요 상태 코드

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

엔드포인트별로 반환할 수 있는 오류 유형은 [API 레퍼런스](https://www.boxhero.io/docs/ko/developers/api/reference)에서 확인할 수 있습니다.

## revision 충돌 처리

입출고 내역을 [수정](https://www.boxhero.io/docs/ko/developers/api/reference/transactions/update-transaction)하거나 [삭제](https://www.boxhero.io/docs/ko/developers/api/reference/transactions/delete-transaction)하려면 마지막으로 확인한 `revision`을 함께 보내 주세요. 그사이 다른 사람이 내역을 변경했다면 `revision`이 맞지 않아 요청이 `403`으로 거부되며, `code`가 `tx-modify-revision-mismatch`로 반환됩니다. `code`로 분기해 내역을 다시 조회하고 변경 사항을 확인한 뒤, 새 `revision`으로 다시 시도해 주세요.

```js
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으로 다시 시도합니다.
  }
}
```