다음을 통해 공유

Azure Cosmos DB에 대한 HTTP 상태 코드

  • 아티클

이 문서에서는 REST 작업에서 반환하는 HTTP 상태 코드를 제공합니다.

‘코드’ 설명
200 OK 다음 REST 작업 중 하나가 정상적으로 완료되었습니다.

- GET 리소스에서
- PUT 리소스에서
- POST 리소스에서
- POST 저장 프로시저 리소스에서 저장 프로시저를 실행합니다.
201 생성됨 리소스를 만들기 위한 POST 작업이 정상적으로 완료되었습니다.
204 콘텐츠 없음 DELETE 작업이 정상적으로 완료되었습니다.
400 잘못된 요청 요청 본문의 JSON, SQL 또는 JavaScript가 잘못되었습니다.

또한 리소스의 필수 속성이 없거나 리소스에 대한 POST 또는 PUT 본문에 설정되어 있지 않아도 400이 반환될 수 있습니다.

그리고 계정에 대해 설정된 것보다 더 높은 수준의 일관성으로 GET 작업의 일관성 수준을 재정의해도 400이 반환됩니다.

x-ms-documentdb-partitionkey가 필요한 요청이 포함되지 않은 경우에도 400이 반환됩니다.
401 권한 없음 헤더가 요청된 리소스에 Authorization 대해 유효하지 않은 경우 401이 반환됩니다.
403 사용할 수 없음 인증 토큰이 만료되었습니다.

리소스 할당량에 도달하면 리소스를 POST 만드는 작업 중에 403 코드도 반환됩니다. 이 시나리오의 예는 프로비전된 스토리지에 도달한 컬렉션에 문서를 추가하려고 하는 경우입니다.

저장 프로시저, 트리거 또는 UDF가 높은 리소스 사용량에 대한 플래그가 지정되고 실행이 차단된 경우에도 403이 반환될 수 있습니다.

Azure Cosmos DB 계정에 구성된 방화벽 규칙이 요청을 차단할 때 403 사용할 수 없음 오류가 반환됩니다. 허용 목록 외의 컴퓨터에서 발생한 모든 요청에는 403 응답이 수신됩니다.

403.3 – 이 상태 코드는 수동 장애 조치(failover) 작업 중에 쓰기 요청에 대해 반환됩니다. 이 상태 코드는 드라이버가 쓰기 요청을 새 쓰기 지역으로 전달하는 리디렉션 코드로 사용됩니다. 직접 REST 클라이언트는 DatabaseAccount에 GET을 수행하여 현재 쓰기 지역을 식별하고 해당 엔드포인트로 쓰기 요청을 전달해야 합니다.
404 찾을 수 없음 더 이상 없는 리소스에 대해 작업을 수행했습니다. 리소스가 이미 삭제된 경우를 예로 들 수 있습니다.
408 요청 시간 초과 요청이 할당된 시간 내에 완료되지 않았습니다. 쿼리 내의 저장 프로시저, 트리거 또는 UDF 실행이 최대 실행 시간 이내에 완료되지 않으면 이 코드가 반환됩니다.
409 충돌 PUT 또는 POST 작업에서 리소스에 대해 제공한 ID를 기존 리소스에서 사용 중입니다. 이 문제를 해결하려면 리소스에 대해 다른 ID를 사용합니다. 분할된 컬렉션의 경우 ID는 동일한 파티션 키 값을 가진 모든 문서 내에서 고유해야 합니다.
412 사전 조건 실패 작업에서 지정한 eTag가 서버에서 제공되는 버전과 다릅니다(즉, 낙관적 동시성 오류). 리소스의 최신 버전을 확인하고 요청의 eTag를 업데이트한 후에 요청을 다시 시도해야 합니다.
413 엔터티가 너무 큼 요청의 문서 크기가 요청에 대해 허용되는 문서 크기를 초과했습니다. 허용되는 최대 문서 크기는 2MB입니다.
423 잠김 다른 스케일링 작업이 진행 중이므로 처리량 스케일링 작업을 수행할 수 없습니다.
424 실패한 종속성 TransactionalBatch 작업의 트랜잭션 범위 내에서 문서 작업이 실패하면 일괄 처리 내의 다른 모든 작업은 실패한 종속성으로 간주됩니다. 이 상태 코드는 동일한 트랜잭션 범위 내의 다른 오류로 인해 현재 작업이 실패한 것으로 간주되었음을 나타냅니다.
429 요청이 너무 많음 컬렉션이 프로비전된 처리량 한도를 초과했습니다. 서버에서 일정 시간이 경과하면 지정한 서버에서 다시 시도한 후 요청을 다시 시도합니다. 자세한 내용은 요청 단위를 참조하세요.
449 다시 시도 작업에 일시적인 오류가 발생했습니다. 이 코드는 쓰기 작업에서만 발생합니다. 작업을 다시 시도해도 안전합니다.
500 내부 서버 오류 예기치 않은 서비스 오류로 인해 작업이 실패했습니다. 지원에 문의 Azure 지원 문제 제출을 참조하세요.
503 서비스를 사용할 수 없음 서비스를 사용할 수 없어 작업을 완료할 수 없습니다. 이 상황은 네트워크 연결 또는 서비스 가용성 문제로 인해 발생할 수 있습니다. 작업을 다시 시도해도 안전합니다. 문제가 지속되면 고객 지원 팀에 문의하세요.

HTTP 하위 상태 코드

Azure Cosmos DB에서 CMK(Customer-Managed 키)를 사용하는 경우 오류가 있는 경우 Azure Cosmos DB는 응답의 HTTP 하위 상태 코드와 함께 오류 세부 정보를 반환합니다. 이 하위 상태 코드를 사용하여 문제의 근본 원인을 디버그할 수 있습니다. 현재 Azure Cosmos DB는 다음 하위 상태 코드를 지원합니다.

서버 쪽 문제에 대한 하위 상태 코드

다음 하위 상태 코드는 서버 쪽 문제에 대해 Azure Cosmos DB에서 지원됩니다.

하위 상태 코드 설명
4000(Azure AD 토큰을 가져오기/액세스하지 못했음) 이 오류는 Azure Cosmos DB가 Azure Active Directory(Azure AD) 액세스 토큰을 가져올 수 없는 경우에 발생합니다. 이 토큰은 Azure Cosmos DB가 Key Vault 액세스하는 데 필요합니다. 이 오류는 네트워킹 문제 또는 데이터 센터 문제로 인해 발생할 수 있으며 사용자가 작업을 수행할 수 있는 것이 아닙니다. Azure Cosmos DB 팀에 문의하여 문제를 resolve 지원 요청을 만듭니다.
4001(Azure AD 서비스를 사용할 수 없음) 이 오류는 Azure AD 서비스가 중단되었거나 문제가 있는 경우에 발생합니다. Azure 중단 dashboard 검사 기존 중단이 있는지 확인할 수 있습니다. 이러한 중단은 일반적으로 몇 시간 내에 해결됩니다. Azure AD 팀에 문의하여 보고 있는 문제를 알리는 것이 가장 좋습니다. Azure AD 팀에서 문제가 없는 것으로 확인되면 Azure Cosmos DB 팀에 문의하여 해결을 위한 지원 요청을 만듭니다.
4004(Key Vault 서비스를 사용할 수 없음) 이 오류는 Azure Cosmos DB가 Key Vault 액세스를 시도하지만 서비스를 사용할 수 없는 경우에 발생합니다. 이는 네트워킹 문제가 Key Vault 도달하거나 서비스 자체가 중단되었을 수 있기 때문일 수 있습니다. Azure 중단 dashboard 검사 기존 중단이 있는지 확인할 수 있습니다. 이러한 중단은 일반적으로 몇 시간 내에 해결됩니다. Key Vault 팀에 문의하여 보고 있는 문제를 알리는 것이 가장 좋습니다. Key Vault 팀에서 문제가 없는 것으로 확인되면 Azure Cosmos DB 팀에 문의하여 해결을 위한 지원 요청을 만듭니다.
4007(내부 서버 오류) 이는 내부 서버 오류이며 입력 바이트가 base64 형식이 아닌 경우에 발생합니다.
4008(Key Vault 내부 서비스 오류) 이 오류는 Azure Cosmos DB가 Key Vault 액세스할 수 없는 경우에 발생합니다. 네트워킹 문제 또는 Key Vault 서비스 자체가 중단된 경우일 수 있습니다. Azure 중단 dashboard 검사 기존 중단이 있는지 확인할 수 있습니다. 이러한 중단은 일반적으로 몇 시간 내에 해결됩니다. Key Vault 팀에 문의하여 보고 있는 문제를 알리는 것이 가장 좋습니다. Key Vault 팀에서 문제가 없는 것으로 확인되면 Azure Cosmos DB 팀에 문의하여 해결을 요청합니다.
1013(컬렉션 만들기 작업이 진행 중) 컬렉션을 만들 때 시간 제한 예외가 발생하면 읽기 작업을 수행하여 컬렉션이 성공적으로 만들어졌는지 확인합니다. 읽기 작업은 컬렉션 만들기 작업이 성공할 때까지 예외를 발생시킵니다. 읽기 작업에서 상태 코드가 404이고 하위 상태 코드가 1013인 예외가 throw되는 경우 컬렉션 만들기 작업이 여전히 진행 중임을 의미합니다. 200 또는 201 상태 코드를 가져올 때까지 읽기 작업을 다시 시도하면 이러한 코드를 통해 컬렉션이 성공적으로 만들어졌는지 알 수 있습니다.

최종 사용자 문제에 대한 하위 상태 코드

다음 하위 상태 코드는 최종 사용자로 인한 문제에 대해 Azure Cosmos DB에서 지원됩니다.

하위 상태 코드 설명
4002(Key Vault Azure AD 대한 권한을 부여하지 않거나 키를 사용하지 않도록 설정됨) 이 문제는 Key Vault 액세스 정책에서 Azure Cosmos DB ID를 제거했거나 키를 사용하지 않도록 설정한 경우에 발생합니다. 이 문제는 일반적으로 최종 사용자에 의해 발생합니다. 이 오류가 발생하면 Azure Cosmos DB가 Key Vault 액세스할 수 있고 키가 사용하도록 설정되어 있는지 확인합니다.
4003(키를 찾을 수 없음) 이 문제는 키가 Key Vault 삭제되는 경우에 발생합니다. 이 문제는 일반적으로 최종 사용자에 의해 발생합니다. 고객 관리형 키와 함께 Azure Cosmos DB를 사용하기 위한 필수 구성 요소 중 하나는 Key Vault 일시 삭제 및 제거 보호가 사용하도록 설정되어 있다는 것입니다. 즉, 삭제된 키를 복구하고 Azure Cosmos DB에 대한 액세스를 복원할 수 있습니다.
4005(키를 래핑하거나 래핑 해제할 수 없음) 이 오류는 Key Vault 키를 래핑하거나 래핑을 해제할 수 없는 경우에 발생합니다. 이 문제는 일반적으로 최종 사용자에 의해 발생합니다. 이 오류의 가능한 원인 중 하나는 Key Vault 키를 회전했기 때문에 최신 키를 사용하여 암호화된 Blob을 디코딩하지 못했기 때문입니다. 이 오류를 resolve 위해 최근에 사용하지 않도록 설정된 키를 사용하도록 설정하면 약 1시간 후에 해결됩니다. 문제가 2시간 넘게 해결되지 않으면 Azure Cosmos DB에 문제를 전달합니다.
4006(키 URL이 잘못됨) 이 오류는 Key Vault URL에 키 버전을 포함하는 경우 프로비전 중에 발생합니다. 이 오류는 종종 최종 사용자에 의해 발생합니다. 이 오류를 resolve 버전을 제거하고 다시 시도합니다. 예를 들어 형식으로 URL을 https://<KeyVaultName>.vault.azure.net/keys/<KeyName>/<KeyVersion>사용한 경우 를 로 업데이트합니다. https://<KeyVaultName>.vault.azure.net/keys/<KeyName>/
4009(KEY VAULT DNS 이름을 확인할 수 없음) 이 오류는 잘못된 Key Vault 이름을 사용했기 때문에 Key Vault DNS 이름을 확인할 수 없는 경우에 발생합니다. 이 오류는 최종 사용자에 의해 발생합니다. resolve Key Vault 이름을 수정하고 다시 시도합니다.

참고 항목