> For the complete documentation index, see [llms.txt](https://docs.roboflow.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.roboflow.com/reference/ko/errors-and-status-codes.md).

# 오류 및 상태 코드

Roboflow의 개발자 도구들은 소수의 오류 범주를 공유하며, 각 도구에서 다르게 표시됩니다. 이 페이지는 이러한 범주를 가로지르는 참고 자료입니다.

## CLI 종료 코드

CLI는 스크립트와 AI 에이전트가 출력을 파싱하지 않고도 결과에 따라 분기할 수 있도록, 잘 정의된 네 가지 종료 코드를 사용합니다:

| 종료 코드 | 의미                                                      |
| ----- | ------------------------------------------------------- |
| `0`   | 성공                                                      |
| `1`   | 일반 오류(잘못된 입력, 네트워크 실패, 예상치 못한 서버 응답)                    |
| `2`   | 인증 실패(누락되었거나 유효하지 않은 API 키, 선택된 워크스페이스 없음)              |
| `3`   | 리소스를 찾을 수 없음(프로젝트, 버전, 워크플로, 배포 등)이 존재하지 않거나 키에서 볼 수 없음 |

In `--json` 모드에서 CLI는 성공 시 구조화된 출력을 stdout에 쓰고 실패 시 JSON 오류 객체를 stderr에 쓰며, 파이프라인이 안전하게 파싱될 수 있도록 stdout은 비워 둡니다:

```bash
roboflow --json project get nonexistent 2>error.json
echo $?       # 3
cat error.json
# {"error": {"message": "프로젝트 'nonexistent'를 찾을 수 없습니다", "hint": "'roboflow project list'를 실행하여 프로젝트를 확인하세요."}}
```

## SDK 예외

Python SDK는 실패 시 Python 예외를 발생시킵니다. 가장 흔히 접하게 될 유형은 다음과 같습니다:

| 예외                                                   | 언제                                                                                      |
| ---------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `RuntimeError`                                       | 작업이 논리적으로 유효하지 않음 - 예: 호출 `restore()` 휴지통에 있지 않은 프로젝트에서 호출하거나, 아직 생성되지 않은 버전에서 학습하는 경우. |
| `ValueError`                                         | 전달된 인수가 잘못 형식화됨 - 예: 인식되지 않는 `model_format` 에 대해 `Version.download()`.                  |
| `roboflow.adapters.rfapi.RoboflowError`              | REST API가 2xx가 아닌 응답을 반환했습니다. 예외 문자열에는 서버의 오류 본문이 들어 있습니다.                              |
| `roboflow.adapters.deploymentapi.DeploymentApiError` | 다음과 동일: `RoboflowError` 전용 배포 서비스에 대해.                                                  |
| `requests.exceptions.HTTPError` / `ConnectionError`  | 네트워크 수준의 실패(DNS, TLS, 타임아웃).                                                            |

경험칙: catch `RuntimeError` 논리적 문제에 대해, `RoboflowError` 서버 측 거부에 대해 캐치하고, 나머지는 모두 전파되도록 두세요.

```python
from roboflow.adapters import rfapi

try:
    project.restore()
except RuntimeError as e:
    print(f"복원할 수 없습니다: {e}")
except rfapi.RoboflowError as e:
    print(f"서버가 요청을 거부했습니다: {e}")
```

다음을 참조하세요 [로깅 및 디버깅](/reference/ko/platform/python-sdk/logging-and-debugging.md) 예외만으로는 충분하지 않을 때 기본 HTTP 요청을 검사하는 방법은 여기를 참조하세요.

## REST API 상태 코드

REST API는 표준 HTTP 상태 코드를 사용합니다. Roboflow 고유 동작:

| 상태    | 의미                                                                                                                                                                     |
| ----- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200` | 성공. 응답 본문은 JSON입니다.                                                                                                                                                    |
| `204` | 성공, 본문 없음(일부에 사용됨 `PATCH` / `DELETE` 엔드포인트).                                                                                                                           |
| `400` | 형식이 잘못된 요청 - 필수 필드 누락, 잘못된 구조, 유효하지 않은 값.                                                                                                                              |
| `401` | 인증 실패.  `api_key`유효하지 않은 키이거나 작업에 필요한 범위가 없는 키입니다.                                                                                                                     |
| `402` | 결제가 필요합니다. 워크스페이스의 요금제가 요청된 작업을 지원하지 않습니다. 추론의 경우, 이는 모델 또는 아키텍처가 크레딧 기반 요금제에서만 이용 가능하거나 워크스페이스의 월별 Hosted API 추론 할당량이 소진되었음을 의미합니다. 응답 본문에는  `AccessException` 오류 유형. |
| `403` | 금지됨. 키는 인증되었지만 대상 워크스페이스 또는 리소스에 대한 접근 권한이 없습니다.                                                                                                                       |
| `404` | 찾을 수 없음. 워크스페이스, 프로젝트, 버전, 워크플로 또는 기타 리소스가 존재하지 않거나(또는 키에서 볼 수 없습니다).                                                                                                  |
| `409` | 충돌. 리소스가 요청된 작업을 방해하는 상태에 있습니다(예: 상위 프로젝트도 휴지통에 있는 버전 복원).                                                                                                             |
| `423` | 잠김. 워크스페이스 결제가 일시 중지되었습니다 - 사유는 응답 본문을 참조하세요.                                                                                                                          |
| `429` | 속도 제한됨. 속도를 늦추고 지수 백오프로 다시 시도하세요.                                                                                                                                      |
| `5xx` | 서버 오류. 백오프로 안전하게 다시 시도할 수 있습니다.                                                                                                                                        |

### 표준 오류 본문

오류는 최소한 최상위  `error` 필드를 포함한 JSON으로 반환됩니다:

```json
{
  "error": "프로젝트 'nonexistent'를 찾을 수 없습니다"
}
```

일부 엔드포인트에는 또한  `hint` 또는 구조화된 오류 객체도 포함됩니다 - 자세한 내용은  [REST API](/reference/ko/platform/rest-api.md) 아래의 엔드포인트별 문서를 참조하세요.

### 필수 범위

API 키에는 리소스별 범위가 포함됩니다. 쓰기 작업에서 401이 발생하는 것은 종종 키에 해당  `*:update` 또는 `*:write`  범위가 없다는 뜻입니다. 리소스를 읽을 수 있더라도 마찬가지입니다. 범위 참조는  [범위 지정 API 키](/reference/ko/authentication/authentication/scoped-api-keys.md) 를 참조하세요.

## 도구 간 오류 매핑

| 상황                  | CLI 종료 | SDK                                      | REST  |
| ------------------- | ------ | ---------------------------------------- | ----- |
| API 키 누락 / 유효하지 않음  | `2`    | `RoboflowError` ("401")                  | `401` |
| 리소스를 찾을 수 없음        | `3`    | `RoboflowError` ("404") / `RuntimeError` | `404` |
| 요금제 제한 / 할당량 초과     | `1`    | `RoboflowError` ("402")                  | `402` |
| 잘못된 입력 / 형식이 잘못된 요청 | `1`    | `ValueError` / `RoboflowError` ("400")   | `400` |
| 서버 오류 / 일시적         | `1`    | `RoboflowError` ("5xx")                  | `5xx` |

재시도를 설정할 때 이 표를 사용하세요:  `2` / 401은 절대 자동 재시도하면 안 됩니다(키가 더 유효해지지 않기 때문입니다),  `3` / 404는 절대 재시도하면 안 되지만,  `1` 5xx 응답의 경우 지수 백오프로 재시도할 후보입니다.