에러

실패한 요청은 HTTP 에러 상태와 error 객체를 반환합니다.

{
  "error": {
    "code": "PROJECT_NOT_FOUND_EXCEPTION",
    "message": "프로젝트를 찾을 수 없습니다."
  }
}

필드	설명
error.code	에러 코드. 언어와 관계없이 같으므로 이 값으로 분기합니다
error.message	사용자에게 보여 줄 수 있는 설명
error.details	추가 정보. 일부 에러에만 포함

예를 들어 요청 본문이 올바르지 않으면 error.details.property에 처음 발견된 잘못된 필드를 담습니다.

{
  "error": {
    "code": "INVALID_REQUEST_BODY_EXCEPTION",
    "message": "요청 값이 올바르지 않습니다.",
    "details": {
      "property": "keyword"
    }
  }
}

요청 ID

모든 응답은 X-YouViCo-Request-Id 헤더에 16진수 32자의 ID를 담습니다.

X-YouViCo-Request-Id: 4bf92f3577b34da6a3ce929d0e0e4736

실패한 요청은 이 값을 함께 기록하고, 에러를 문의할 때 이 값을 전달할 수 있습니다.

HTTP 상태 코드

상태	의미
400 Bad Request	필드가 없거나 올바르지 않음, 또는 커서 형식 오류
401 Unauthorized	API 키나 OAuth 액세스 토큰이 없거나 올바르지 않거나 만료됨
403 Forbidden	이 작업을 할 권한이 없음
404 Not Found	리소스가 없거나 접근할 수 없음
409 Conflict	중복된 리액션처럼 현재 상태와 충돌
413 Content Too Large	요청 본문이 너무 큼
415 Unsupported Media Type	요청 본문을 JSON으로 보내지 않음
429 Too Many Requests	요청 제한 초과
500 Internal Server Error	서버 오류
503 Service Unavailable	서비스 점검 중

공통 에러 코드

모든 엔드포인트에서 발생할 수 있는 에러입니다.

코드	상태	발생 조건
INVALID_REQUEST_BODY_EXCEPTION	400	요청 본문이 올바르지 않거나 커서 형식이 잘못됨
INVALID_REQUEST_EXCEPTION	400	잘못된 요청
INVALID_AUTHENTICATION_HEADER_EXCEPTION	400	Authorization 헤더가 Bearer YOUR_API_KEY 형식이 아님
INVALID_API_KEY_EXCEPTION	401	API 키가 없거나 더 이상 활성 상태가 아님
INVALID_ACCESS_TOKEN_EXCEPTION	401	OAuth 액세스 토큰이 올바르지 않거나 만료됨
ACCESS_DENIED_EXCEPTION	403	리소스에 접근할 권한이 없음
FORBIDDEN_SCOPE_EXCEPTION	403	키나 연결에 엔드포인트가 요구하는 API 권한이 없음
FORBIDDEN_ROLE_EXCEPTION	403	역할상 허용되지 않는 작업
USER_SUSPENDED_EXCEPTION	403	정지된 계정
NOT_IN_WORKSPACE_EXCEPTION	403	워크스페이스 멤버가 아님
FORBIDDEN_STATUS_EXCEPTION	403	비활성 워크스페이스 멤버
PROJECT_ARCHIVED_EXCEPTION	403	보관된 프로젝트라 변경할 수 없음
ROUTE_NOT_FOUND_EXCEPTION	404	URL 경로가 엔드포인트가 아님
WORKSPACE_NOT_FOUND_EXCEPTION	404	존재하지 않는 워크스페이스
REQUEST_BODY_SIZE_LIMIT_EXCEEDED_EXCEPTION	413	요청 본문이 너무 큼
UNSUPPORTED_CONTENT_TYPE_EXCEPTION	415	요청 본문을 application/json으로 보내지 않음
RATE_LIMIT_EXCEEDED_EXCEPTION	429	엔드포인트의 요청 제한 초과
INTERNAL_UNEXPECTED_EXCEPTION	500	예기치 않은 서버 오류
DATABASE_UNAVAILABLE_EXCEPTION	500	지금은 요청을 처리할 수 없음. 잠시 후 다시 시도
SERVICE_MAINTENANCE_EXCEPTION	503	서비스 점검 중