공통 규약

모든 엔드포인트는 동일한 공통 응답 형식과 에러 처리 규약을 공유합니다. 이 페이지를 한 번 읽어두면 이후 각 엔드포인트 설명이 짧아집니다.

성공 응답

성공 시 결과는 항상 ApiResponse 형식으로 감싸여 반환됩니다.

{
  "success": true,
  "status_code": 200,
  "data": { }
}

필드	타입	설명
success	boolean	성공 여부 (성공 시 true)
status_code	integer	HTTP 상태 코드
data	any | null	실제 반환 데이터 (엔드포인트마다 다름)

예시 — 파이펫 구성 조회 GET /api/v1/config/pipette

{
  "success": true,
  "status_code": 200,
  "data": { "1": "8ch_200ul", "2": null }
}

에러 응답

에러 시 HTTP 상태 코드가 4xx/5xx로 내려가며, 본문은 detail 안에 실패한 ApiResponse가 담깁니다.

{
  "detail": {
    "success": false,
    "status_code": 400,
    "data": "오류 메시지 문자열"
  }
}

에러 코드 매핑

애플리케이션은 내부 예외를 다음 규칙으로 HTTP 상태 코드에 매핑합니다.

HTTP	발생 조건	의미
400 Bad Request	ValueError, KeyError	잘못된 파라미터/키 (예: 존재하지 않는 파이펫 타입)
500 Internal Server Error	그 외 모든 예외	예기치 못한 서버 오류
503 Service Unavailable	DriverError, 서비스 미준비	하드웨어 드라이버 오류 또는 서비스가 아직 초기화되지 않음

503의 두 가지 의미

• 서비스 미준비: 서버 부팅 직후 서비스 wiring 전. 잠시 후 재시도하세요.
• 드라이버 오류: 모터/IO 통신 실패. 로봇 상태(GET /api/v1/action/robot/status)와 연결을 확인하세요.

로봇 상태 게이트

일부 동작 엔드포인트는 실행 전에 로봇 상태를 검사합니다. PAUSED 상태에서는 대기하고, STOP/ERROR 상태에서는 거부될 수 있습니다. 동작을 호출하기 전에 GET /api/v1/action/robot/status로 상태를 확인하는 것이 안전합니다.