> 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 에이전트가 출력을 파싱하지 않고도 결과에 따라 분기할 수 있도록 잘 정의된 4개의 종료 코드를 사용합니다:

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

다음의 `--json` 모드에서 CLI는 성공 시 구조화된 출력을 stdout에 쓰고, 실패 시 JSON 오류 객체를 stderr에 써서 stdout을 비워 둡니다. 이렇게 하면 파이프라인을 안전하게 파싱할 수 있습니다:

```bash
roboflow --json project get nonexistent 2>error.json
echo $?       # 3
cat error.json
# {"error": {"message": "Project 'nonexistent' not found", "hint": "Run 'roboflow project list' to see your projects."}}
```

## SDK 예외

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

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

경험칙: `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`가 없거나, 유효하지 않거나, 작업에 필요한 범위(scope)가 없는 키.                                                                                                     |
| `402` | 결제가 필요함. 워크스페이스의 요금제가 요청된 작업을 지원하지 않습니다. 추론의 경우, 이는 모델 또는 아키텍처가 크레딧 기반 요금제에서만 사용 가능하거나 워크스페이스의 월별 Hosted API 추론 할당량에 도달했음을 의미합니다. 응답 본문에는 `AccessException` 오류 유형이 포함됩니다. |
| `403` | 금지됨. 키는 인증되었지만 대상 워크스페이스 또는 리소스에 대한 접근 권한이 없습니다.                                                                                                                          |
| `404` | 찾을 수 없음. 워크스페이스, 프로젝트, 버전, 워크플로 또는 기타 리소스가 존재하지 않거나(또는 키에서 보이지 않음).                                                                                                       |
| `409` | 충돌. 리소스가 요청된 작업을 방해하는 상태에 있음(예: 상위 프로젝트도 Trash에 있는 버전을 복원하려는 경우).                                                                                                         |
| `423` | 잠김. 워크스페이스 결제가 일시 중지됨 - 이유는 응답 본문을 참조하세요.                                                                                                                                 |
| `429` | 요청 제한. 응답에 `Retry-After` 헤더가 있으면, 재시도하기 전에 적어도 그만큼의 초를 기다리세요. 그렇지 않으면 지수 백오프로 재시도하세요.                                                                                     |
| `5xx` | 서버 오류. 백오프로 안전하게 재시도할 수 있습니다.                                                                                                                                             |

### 표준 오류 본문

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

```json
{
  "error": "Project 'nonexistent' not found"
}
```

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

### 학습 읽기 속도 제한

학습 읽기 엔드포인트(`GET /:workspace/:project/:version/v2/trainings`, `.../v2/trainings/get`와 `.../v2/trainings/recipe`)는 API 키와 워크스페이스별로 요청 수를 계산합니다. 동일한 IP 주소에서 발생한 다른 트래픽은 사용자에게 불리하게 계산되지 않습니다. 제한된 요청은 `429` 와 함께 `Retry-After` 헤더 및 다음 본문을 반환합니다:

```json
{
  "error": {
    "code": "training_read_rate_limit_exceeded",
    "message": "Too many training read requests. Please retry later."
  }
}
```

누락되었거나 유효하지 않은 API 키로 반복 요청하면 IP 주소별로 별도로 제한됩니다. 그런 요청은 `429` 를 평문 본문과 함께 반환하며 `Retry-After` 헤더는 포함하지 않습니다.

### 필수 범위

API 키에는 리소스별 범위(scope)가 포함됩니다. 쓰기 작업에서 401이 발생하면 종종 키에 해당 `*:update` 또는 `*:write` 범위가 없다는 뜻입니다. 리소스를 읽을 수 있더라도 마찬가지입니다. 범위 참조는 [Scoped API Keys](/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 응답의 경우는 백오프로 재시도할 후보입니다.