> 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).

# 오류 및 상태 코드

CLI 종료 코드, SDK 예외, REST API 오류 응답에 대한 참조입니다.

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

## CLI 종료 코드

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

| 종료 코드 | 의미                                                      |
| ----- | ------------------------------------------------------- |
| `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": "프로젝트 'nonexistent'를 찾을 수 없음", "hint": "프로젝트를 보려면 'roboflow project list'를 실행하세요."}}
```

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

### 표준 오류 본문

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

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

일부 엔드포인트는 또한 `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": "학습 읽기 요청이 너무 많습니다. 나중에 다시 시도하세요."
  }
}
```

API 키가 없거나 유효하지 않은 반복 요청은 IP 주소 기준으로 별도로 제한됩니다. 이러한 요청은 `429` 을(를) 평문 본문과 동일한 `Retry-After` 및 `RateLimit-*` 헤더와 함께 반환합니다.

### 필수 범위

API 키에는 리소스별 범위가 포함됩니다. 쓰기 작업에서 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 응답의 경우 백오프를 적용한 재시도의 후보가 됩니다.