참고자료

오류 및 비율 제한

REST 오류는 이 봉투를 사용합니다. 지원 요청 ID를 유지하고 API 키를 기록하지 마세요.

코드 및 requestId로 시작

안정적인 코드는 프로그램에 무슨 일이 일어났는지 알려줍니다. 사람이 읽을 수 있는 메시지는 이 요청을 설명합니다. 지원팀에 문의할 때 requestId를 저장하세요.

JSON error response

{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "The API key is missing, invalid, or revoked.",
    "requestId": "req_..."
  }
}

401의 경우 헤더가 Bearer으로 시작하고 그 뒤에 공백 하나와 활성 키가 오는지 확인하세요. 403의 경우 키 생성 시 선택한 계정 계획과 범위를 확인하세요.

409 또는 422의 경우 PUT 완료, Content-Type 일치, 업로드된 바이트 수가 sizeBytes와 같은지 확인합니다. 임시 URL이 만료된 경우 새로운 업로드 작업을 생성하세요.

코드	HTTP	의미
BAD_REQUEST	400 / 409	HTTP 400은 요청 본문이 유효하지 않음을 의미합니다. HTTP 409는 현재 상태에서는 업로드를 완료할 수 없음을 의미합니다.
UNAUTHORIZED	401	API 키가 누락되었거나 잘못되었거나 취소되었습니다.
PAID_PLAN_REQUIRED	403	계정에 적합한 유료 요금제가 없습니다.
INSUFFICIENT_SCOPE	403	API 키에는 필수 범위가 포함되어 있지 않습니다.
NOT_FOUND	404	소유한 업로드, 파일 또는 공유를 찾을 수 없습니다.
UPLOAD_NOT_READY	409	업로드된 개체가 완료될 준비가 되지 않았습니다.
FILE_TOO_LARGE	413	파일이 적용 가능한 크기 제한을 초과합니다.
OBJECT_VALIDATION_FAILED	422	업로드된 객체가 검증에 실패했습니다.
QUOTA_EXCEEDED	429	업로드 할당량이 소진되었습니다.
RATE_LIMIT_EXCEEDED	429	API 요청 속도가 소진되었습니다.
SERVICE_UNAVAILABLE	503	필수 서비스를 일시적으로 사용할 수 없습니다.

Retry-After 이후에만 429를 다시 시도하세요. 지수 백오프를 사용하여 임시 503 오류를 재시도합니다. 잘못된 400, 401 또는 403 요청을 자동으로 재시도하지 마세요.