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

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

에서 `--json` 모드에서는 CLI가 성공 시 stdout에 구조화된 출력을 쓰고, 실패 시 stderr에 JSON 오류 객체를 쓰며, 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, 시간 초과).                                                         |

경험상 다음을 잡으세요: `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}")
```

참조하세요 [로깅 및 디버깅](https://docs.roboflow.com/reference/ko/platform/python-sdk/logging-and-debugging.md) 예외만으로는 충분하지 않을 때 내부 HTTP 요청을 검사하는 방법에 대해.

## REST API 상태 코드

REST API는 표준 HTTP 상태 코드를 사용합니다. Roboflow 특유의 동작은 다음과 같습니다:

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

### 표준 오류 본문

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

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

일부 엔드포인트에는 또한 `hint` 또는 구조화된 오류 객체가 포함됩니다 - 아래의 엔드포인트별 문서를 참조하세요 [REST API](https://docs.roboflow.com/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-*` 헤더를 반환합니다.

### 필수 scope

API 키에는 리소스별 scope가 포함됩니다. 쓰기 작업에서 401이 발생하는 경우, 해당 키에 대응하는 `*:update` 또는 `*:write` scope가 없음을 의미하는 경우가 많습니다. 리소스를 읽을 수 있더라도 마찬가지입니다. 참조하세요 [고급 API 키](https://docs.roboflow.com/reference/ko/authentication/authentication/scoped-api-keys.md) 에서 scope 참고 자료를 확인하세요.

## 도구 간 오류 매핑

| 상황                 | 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` |

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