오류 코드 (Error codes)
오류가 반환되는 방식 (How errors are returned)
출처: 문서
본문
Workers API의 경우 R2 작업은 잡을 수 있는 예외(exception)를 던져요. 오류 코드는 message 속성의 끝에 포함돼요.
try {
await env.MY_BUCKET.put("my-key", data, { customMetadata: largeMetadata });
} catch (error) {
console.error(error.message);
// "put: Your metadata headers exceed the maximum allowed metadata size. (10012)"
}
S3 호환 API의 경우 오류는 응답 본문에서 XML로 반환돼요.
<?xml version="1.0" encoding="UTF-8"?>
<Error>
<Code>NoSuchKey</Code>
<Message>The specified key does not exist.</Message>
</Error>
오류 코드 참조 (Error code reference)
인증 및 권한 부여 오류 (Authentication and authorization errors)
| 오류 코드 | S3 코드 | HTTP 상태 | 세부 사항 | 권장 해결 방법 | | 10002 | Unauthorized | 401 | 인증 자격 증명이 없거나 잘못됨. | API 토큰이나 액세스 키 자격 증명이 올바르고 만료되지 않았는지 확인해요. | | 10003 | AccessDenied | 403 | 요청한 작업에 대한 권한이 부족함. | API 토큰이 버킷과 작업에 필요한 권한을 가지고 있는지 확인해요. | | 10018 | ExpiredRequest | 403 | 사전 서명 URL 또는 요청 서명이 만료됨. | 사전 서명 URL이나 서명을 다시 생성해요. | | 10035 | SignatureDoesNotMatch | 403 | 요청 서명이 계산된 서명과 일치하지 않음. | 비밀 키와 서명 알고리즘을 확인해요. URL 인코딩 문제를 확인해요. | | 10042 | NotEntitled | 403 | 계정이 이 기능을 사용할 자격이 없음. | 계정에 R2 구독이 있는지 확인해요. |
버킷 오류 (Bucket errors)
| 오류 코드 | S3 코드 | HTTP 상태 | 세부 사항 | 권장 해결 방법 | | 10005 | InvalidBucketName | 400 | 버킷 이름이 명명 요구 사항을 충족하지 않음. | 버킷 이름은 3-63자, 소문자 영숫자와 하이픈이어야 하고 영숫자로 시작/끝나야 해요. | | 10006 | NoSuchBucket | 404 | 지정한 버킷이 존재하지 않음. | 버킷 이름이 올바른지, 버킷이 계정에 존재하는지 확인해요. | | 10008 | BucketNotEmpty | 409 | 객체를 포함한 버킷은 삭제할 수 없음. | 버킷을 삭제하기 전에 버킷의 모든 객체를 삭제해요. | | 10009 | TooManyBuckets | 400 | 계정 버킷 제한 초과(기본값: 1,000,000개 버킷). | 한도 증가 요청 양식(Limits Increase Request Form) ↗︎을 통해 한도 증가를 요청해요. | | 10073 | BucketConflict | 409 | 버킷 이름이 이미 존재함. | 다른 버킷 이름을 선택해요. 버킷 이름은 계정 내에서 고유해야 해요. |
객체 오류 (Object errors)
| 오류 코드 | S3 코드 | HTTP 상태 | 세부 사항 | 권장 해결 방법 | | 10007 | NoSuchKey | 404 | 지정한 객체 키가 존재하지 않음. Workers API의 경우 get()과 head()는 던지지 않고 null을 반환해요. | 객체 키가 올바른지, 객체가 삭제되지 않았는지 확인해요. | | 10020 | InvalidObjectName | 400 | 객체 키에 잘못된 문자가 있거나 너무 김. | 유효한 UTF-8 문자를 사용해요. 최대 키 길이는 1024바이트예요. | | 100100 | EntityTooLarge | 400 | 객체가 최대 크기를 초과함(단일 업로드 5GiB, 멀티파트 5TiB). | 5GiB보다 큰 객체에는 멀티파트 업로드를 사용해요. 최대 객체 크기는 5TiB예요. | | 10012 | MetadataTooLarge | 400 | 커스텀 메타데이터가 8,192바이트 제한을 초과함. | 커스텀 메타데이터 크기를 줄여요. 모든 커스텀 메타데이터의 최대 총합은 8,192바이트예요. | | 10069 | ObjectLockedByBucketPolicy | 403 | 객체가 버킷 잠금 규칙에 의해 보호되어 수정하거나 삭제할 수 없음. | 보존 기간이 만료될 때까지 기다려요. 버킷 잠금(bucket locks)을 참고해요. |
업로드 및 요청 오류 (Upload and request errors)
| 오류 코드 | S3 코드 | HTTP 상태 | 세부 사항 | 권장 해결 방법 | | 10033 | MissingContentLength | 411 | Content-Length 헤더가 필요하지만 없음. | PUT/POST 요청에 Content-Length 헤더를 포함해요. | | 10013 | IncompleteBody | 400 | 예상된 Content-Length 전에 요청 본문이 종료됨. | 요청 본문 전체를 보내는지 확인해요. 네트워크 중단이나 클라이언트 타임아웃을 확인해요. | | 10014 | InvalidDigest | 400 | 체크섬 헤더 형식이 잘못됨. | 체크섬이 올바르게 인코딩되었는지 확인해요(SHA/CRC 체크섬은 base64). | | 10037 | BadDigest | 400 | 제공된 체크섬이 업로드된 콘텐츠와 일치하지 않음. | 데이터 무결성을 확인하고 업로드를 다시 시도해요. | | 10039 | InvalidRange | 416 | 요청한 바이트 범위를 충족할 수 없음. | 범위 시작이 객체 크기보다 작은지 확인해요. Range 헤더 형식을 확인해요. | | 10031 | PreconditionFailed | 412 | 조건부 헤더(If-Match, If-Unmodified-Since 등)가 충족되지 않음. | 객체의 ETag나 수정 시간이 조건과 일치하지 않음. 다시 가져와서 재시도해요. 조건부 작업(conditional operations)을 참고해요. |
멀티파트 업로드 오류 (Multipart upload errors)
| 오류 코드 | S3 코드 | HTTP 상태 | 세부 사항 | 권장 해결 방법 | | 10011 | EntityTooSmall | 400 | 멀티파트 부분이 최소 크기(5MiB) 미만. 마지막 부분은 예외. | 각 부분(마지막 제외)이 최소 5MiB인지 확인해요. | | 10024 | NoSuchUpload | 404 | 멀티파트 업로드가 존재하지 않거나 중단됨. | uploadId가 올바른지 확인해요. 기본적으로 미완료 멀티파트 업로드는 7일 후 만료돼요. 객체 라이프사이클(object lifecycles)을 참고해요. | | 10025 | InvalidPart | 400 | 업로드 완료 시 하나 이상의 부분을 찾을 수 없음. | 각 부분이 성공적으로 업로드되었는지 확인하고 UploadPart가 반환한 정확한 ETag를 사용해요. | | 10048 | InvalidPart | 400 | 모든 비-후행 부분은 같은 크기여야 함. | 마지막 부분을 제외한 모든 부분의 크기가 동일한지 확인해요. R2는 멀티파트 업로드에 균일한 부분 크기를 요구해요. |
서비스 오류 (Service errors)
| 오류 코드 | S3 코드 | HTTP 상태 | 세부 사항 | 권장 해결 방법 | | 10001 | InternalError | 500 | 내부 오류가 발생함. | 요청을 다시 시도해요. 지속되면 Cloudflare 상태(Status) ↗︎를 확인하거나 지원에 문의해요. | | 10043 | ServiceUnavailable | 503 | 서비스를 일시적으로 사용할 수 없음. | 지수 백오프로 다시 시도해요. Cloudflare 상태(Status) ↗︎를 확인해요. | | 10054 | ClientDisconnect | 400 | 요청이 완료되기 전에 클라이언트가 연결을 끊음. | 네트워크 연결을 확인하고 다시 시도해요. | | 10058 | TooManyRequests | 429 | 요금 제한을 초과함. 여러 동시 요청이 같은 객체 키로 발생하는 경우가 많음(제한: 키당 초당 1회 쓰기). | 여러 클라이언트가 같은 객체 키에 접근하고 있는지 확인해요. R2 한도(R2 limits)를 참고해요. |