오류 및 상태 코드
CLI 종료 코드, SDK 예외 및 REST API 오류 응답에 대한 참조.
마지막 업데이트
도움이 되었나요?
CLI 종료 코드, SDK 예외 및 REST API 오류 응답에 대한 참조.
Roboflow의 개발자 도구들은 소수의 오류 범주를 공유하며, 각 도구에서 다르게 표시됩니다. 이 페이지는 이러한 범주를 가로지르는 참고 자료입니다.
CLI는 스크립트와 AI 에이전트가 출력을 파싱하지 않고도 결과에 따라 분기할 수 있도록, 잘 정의된 네 가지 종료 코드를 사용합니다:
0
성공
1
일반 오류(잘못된 입력, 네트워크 실패, 예상치 못한 서버 응답)
2
인증 실패(누락되었거나 유효하지 않은 API 키, 선택된 워크스페이스 없음)
3
리소스를 찾을 수 없음(프로젝트, 버전, 워크플로, 배포 등)이 존재하지 않거나 키에서 볼 수 없음
In --json 모드에서 CLI는 성공 시 구조화된 출력을 stdout에 쓰고 실패 시 JSON 오류 객체를 stderr에 쓰며, 파이프라인이 안전하게 파싱될 수 있도록 stdout은 비워 둡니다:
roboflow --json project get nonexistent 2>error.json
echo $? # 3
cat error.json
# {"error": {"message": "프로젝트 'nonexistent'를 찾을 수 없습니다", "hint": "'roboflow project list'를 실행하여 프로젝트를 확인하세요."}}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 서버 측 거부에 대해 캐치하고, 나머지는 모두 전파되도록 두세요.
다음을 참조하세요 로깅 및 디버깅 예외만으로는 충분하지 않을 때 기본 HTTP 요청을 검사하는 방법은 여기를 참조하세요.
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으로 반환됩니다:
일부 엔드포인트에는 또한 hint 또는 구조화된 오류 객체도 포함됩니다 - 자세한 내용은 REST API 아래의 엔드포인트별 문서를 참조하세요.
API 키에는 리소스별 범위가 포함됩니다. 쓰기 작업에서 401이 발생하는 것은 종종 키에 해당 *:update 또는 *:write 범위가 없다는 뜻입니다. 리소스를 읽을 수 있더라도 마찬가지입니다. 범위 참조는 범위 지정 API 키 를 참조하세요.
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 응답의 경우 지수 백오프로 재시도할 후보입니다.
마지막 업데이트
도움이 되었나요?
도움이 되었나요?
from roboflow.adapters import rfapi
try:
project.restore()
except RuntimeError as e:
print(f"복원할 수 없습니다: {e}")
except rfapi.RoboflowError as e:
print(f"서버가 요청을 거부했습니다: {e}"){
"error": "프로젝트 'nonexistent'를 찾을 수 없습니다"
}