오류 코드

오류는 모두 같은 봉투예요.

{
  "error": { "code": "RESOURCE_OFFLINE", "message": "Resource is offline", "details": {}, "suggest": null },
  "meta": { "request_id": "…", "timestamp": "…" }
}

• code 로 분기하세요. message 는 사람용 영어 한 문장이에요.
• 남의 것을 가리키면 403 이 아니라 그 엔티티의 *_NOT_FOUND(404)예요.

공통

code	HTTP	뜻
BAD_REQUEST	400	JSON 이 아니거나 읽을 수 없는 요청
VALIDATION_ERROR	400	스키마 위반. details.errors[] 에 path·expected
UNAUTHORIZED	401	인증 없음·무효
FORBIDDEN	403	그 인증 수단으로는 못 하는 일 (예: API 키로 virtual Device 만들기)
NOT_FOUND	404	경로 없음
CONFLICT	409	그 밖의 상태 충돌
PAYLOAD_TOO_LARGE	413	본문 상한 초과
UNPROCESSABLE	422	형식은 맞지만 의미상 불가
RATE_LIMITED	429	한도 초과. Retry-After 동반
INTERNAL_ERROR · SERVICE_UNAVAILABLE	500 · 503	서버 쪽 문제

자주 만나는 것

code	HTTP	뜻 · 할 일
OS_HALTED	409	OS 가 멈춰 있어요. os/boot 뒤에
INSUFFICIENT_CREDITS	402	계정 잔액이 0 이하예요. 명령·virtual Device 만들기·시작·앱 열기가 막혀요. details.balance — 충전 뒤에
RESOURCE_OFFLINE	409	기기의 에이전트가 없어요. 접속 뒤에, 또는 queue_ttl_ms 를 주고
RESOURCE_DISABLED	409	꺼진 기기. enable 뒤에
RESOURCE_BUSY	429	에이전트의 줄(100건)이 꽉 찼어요. 잠시 뒤
REQUEST_ID_CONFLICT	409	같은 request_id 에 다른 입력
COMMAND_OUTCOME_UNKNOWN	504	실행됐는지 몰라요. 같은 request_id 로 다시
COMMAND_IN_PROGRESS · OUTPUT_EXPIRED	409 · 410	출력이 아직 · 이미 지남 (24시간)
SCREEN_UNSUPPORTED · DEVICE_APPS_UNSUPPORTED	422	그 kind 는 화면·설치된 앱 목록을 주지 않아요
AGENT_CONNECTED	409	접속 중인 에이전트의 토큰은 회전할 수 없어요

기기

code	HTTP	뜻 · 할 일
DEVICE_NOT_FOUND	404	/devices* 의 기기가 없거나 남의 것. 옛 /resources* 경로는 RESOURCE_NOT_FOUND
DEVICE_LIMIT_REACHED	409	OS 설정 max_resources (actual·virtual 합계)
DEVICE_KIND_NOT_ALLOWED	422	OS 설정 allowed_kinds 에 없는 kind
DEVICE_KIND_NOT_HOSTABLE	422	클라우드에 띄울 수 없는 kind (mac), 또는 공급자가 못 띄워요
VIRTUAL_DEVICE_LIMIT_REACHED	409	OS 설정 max_virtual_devices
VOLUME_QUOTA_EXCEEDED	409	OS 설정 max_volume_gb
DEVICE_STATE_CONFLICT	409	지금 상태에서 못 하는 동작 (예: 멈추는 중에 시작). actual 에 start·stop·restart·size 도 이것 — details.type
COMPUTE_UNAVAILABLE	503	공급자에 닿지 못했거나 용량이 없어요. 기기는 그 전 상태
RESOURCE_MANAGED_BY_APP	409	virtual 기기의 토큰은 OS 가 관리해요 (토큰 회전, 옛 /resources 경로로 지우기)
STATION_NOT_EMPTY	409	남은 기기·객체 수가 details 에

앱과 Dock

code	HTTP	뜻 · 할 일
APP_NOT_FOUND	404	저장한 앱이 없거나 남의 것
APP_LIMIT_REACHED	409	Station 당 저장한 앱 100개
DOCK_ITEM_INVALID	422	잘못된 Dock 항목. details.index

프로젝트와 빌링

code	HTTP	뜻 · 할 일
PROJECT_NOT_FOUND	404	프로젝트가 없거나 남의 것. 형식이 틀린 id 도 같아요
PROJECT_LIMIT_REACHED	409	사용자당 프로젝트 20개 (기본 프로젝트 포함). details.max_projects
PROJECT_NOT_EMPTY	409	Station 이 남아 있어 프로젝트를 지울 수 없어요. details.stations 에 남은 수
CHECKOUT_NOT_FOUND	404	체크아웃이 없거나 내 계정의 것이 아니에요
CHECKOUT_STATE_CONFLICT	409	이미 끝난 체크아웃
PAYMENT_PROVIDER_UNAVAILABLE	501	아직 구현하지 않은 결제 공급자 (v0.2.0 은 mock 만)

이벤트와 웹훅

code	HTTP	뜻 · 할 일
WEBHOOK_URL_NOT_ALLOWED	422	https 공인 호스트만
EVENT_TICKET_INVALID	401	입장권이 없거나 만료·재사용

WebSocket 닫힘 코드

코드	누구에게	뜻
1012	에이전트	같은 토큰의 새 접속이 이 소켓을 대체했어요
4001	에이전트	토큰이 폐기·회전됐어요. 다시 붙어도 401 — 재접속하지 마세요
4008	에이전트	생존 확인 실패. 평소처럼 재접속해요
4401	이벤트 구독자	입장권 무효
4410	이벤트 구독자	이어 받을 수 없어요 — REST 로 다시 읽고 새로 붙어요