API HTTP 상태 코드와 오류 응답 레퍼런스
업데이트: 2026-10-20
DashCloud API는 성공 시 2xx, 실패 시 4xx(요청 문제) 또는 5xx(서버·노드 문제)와 함께 아래 형식의 JSON 에러를 반환합니다. 에이전트·CLI·MCP가 자동으로 교정할 수 있도록 code와 hint를 함께 제공합니다.
{
"error": {
"code": "VALIDATION_FAILED",
"message": "이미지는 5MB 이하만 업로드할 수 있습니다",
"hint": null,
"docsUrl": null,
"requestId": "req-..."
},
"statusCode": 413,
"path": "/community/uploads",
"timestamp": "2026-10-20T08:00:00.000Z"
}requestId는 서버 로그 추적에 사용합니다. 문의 시 함께 전달해 주세요.
상태 코드 요약
| 상태 | 대표 code | 의미 | 대응 |
|---|---|---|---|
| 400 | VALIDATION_FAILED | 요청 값이 형식·범위에 맞지 않음 | 메시지의 필드를 수정해 재시도 |
| 401 | UNAUTHORIZED | 토큰 없음/만료/위조 | API 키·세션 재발급 |
| 403 | FORBIDDEN · PROJECT_SUSPENDED · PARTNER_MANAGED | 권한 없음, 정지된 프로젝트, 파트너 관리 프로젝트 | 프로젝트 상태·소유권 확인 |
| 404 | NOT_FOUND · PROJECT_NOT_FOUND · SECRET_NOT_FOUND · BACKUP_NOT_FOUND | 대상이 없음 | id/이름 재확인 |
| 409 | CONFLICT · ALREADY_REQUESTED | 중복 생성, 잠금 백업 한도 초과 등 | 기존 리소스 정리 후 재시도 |
| 413 | PAYLOAD_TOO_LARGE | 업로드·배포 번들이 허용 크기 초과 | 파일 분할 또는 크기 축소 |
| 429 | RATE_LIMITED | 요청 빈도 제한 | 잠시 후 재시도 (백오프) |
| 500 | INTERNAL_ERROR | 예기치 못한 서버 오류 | 재시도, 지속 시 문의 |
| 502 | UPSTREAM_ERROR | 외부 저장소·오브젝트 스토리지 등 업스트림 실패 | 잠시 후 재시도 |
| 503/504 | DAEMON_UNAVAILABLE | 노드 데몬 응답 없음/시간 초과 | 재시도, 지속 시 문의 |
자주 만나는 상황
- 배포 413: tar.gz 번들이 배포 상한을 넘었습니다.
node_modules,.venv, 캐시 디렉터리를 제외하고 다시 패키징하세요. - 이미지 업로드 413: 커뮤니티 이미지는 5MB 이하만 허용됩니다(자동 WebP 재인코딩).
- 429: 배포·실행 트리거는 짧은 간격으로 연속 호출하면 제한될 수 있습니다. 실패 시
Retry-After를 존중하세요. - 503 DAEMON_UNAVAILABLE: 노드 유지보수·재시작 중일 수 있습니다. 프로젝트 상태가
CRASHED가 아니라면 잠시 후 재시도로 대부분 해결됩니다. - 401 UNAUTHORIZED: API 키를 재발급하고
Authorization: Bearer <key>헤더 형식을 확인하세요.
실행 중인 봇이 특정 예외로 종료된 경우, 콘솔의 "해결 팁" 배너가 관련 문서와 Q&A 검색 링크를 제안합니다.