Azure IoT Hub 오류 이해 및 해결

2025-07-22

이 문서에서는 IoT Hub를 사용하는 동안 발생할 수 있는 일반적인 오류 코드의 원인과 해결 방법에 대해 설명합니다.

400027 연결이 새 연결에서 강제로 닫힘

디바이스 연결이 끊기고 .NET SDK 및 MQTT 전송 유형을 사용하여 ConnectionStatusChangeReason으로 Communication_Error가 보고되는 경우 400027 ConnectionForcefullyClosedOnNewConnection 오류가 표시될 수 있습니다. 또는 디바이스-클라우드 트윈 작업(예: 보고된 속성 읽기 또는 패치)이나 직접 메서드 호출이 오류 코드 400027으로 인해 실패합니다.

이 오류는 다른 클라이언트가 동일한 ID를 사용하여 IoT Hub에 대한 새 연결을 만들 때 발생하므로 IoT Hub는 이전 연결을 닫습니다. IoT Hub는 둘 이상의 클라이언트가 동일한 ID를 사용하여 연결하는 것을 허용하지 않습니다.

이 오류를 해결하려면 각 클라이언트가 자체 ID를 사용하여 IoT Hub에 연결해야 합니다.

401003 IoT Hub 권한 없음

로그에서 401003 IoTHubUnauthorized로 인해 장치 연결이 끊어진 후 404104 DeviceConnectionClosedRemotely 패턴이 나타나며, 이후 장치가 곧 성공적으로 다시 연결되는 것을 볼 수 있습니다.

또는 다음 오류 메시지 중 하나로 IoT Hub에 대한 요청이 실패합니다.

권한 부여 헤더가 없습니다.
IotHub '*'에 지정된 디바이스 '*'가 포함되어 있지 않습니다.
권한 부여 규칙 '*'은 '*'에 대한 액세스를 허용하지 않습니다.
이 디바이스에 대한 인증 실패, 토큰 또는 인증서 갱신 및 다시 연결
지문이 구성과 일치하지 않음. 지문: SHA1Hash=*, SHA2Hash=*, 구성: PrimaryThumbprint=*, SecondaryThumbprint=*
할당된 권한이 없어 주체 user@example.com 는 /exampleOperation에서 GET을 수행할 수 없습니다.

이 오류는 MQTT의 경우 일부 SDK가 IoT Hub를 사용하여 SAS 토큰이 만료될 때 연결을 끊어 새로 고칠 시기를 알기 때문에 발생합니다. 그래서:

SAS 토큰이 만료됩니다.
IoT Hub가 만료를 확인하고 401003 IoTHubUnauthorized를 사용하여 디바이스 연결을 끊습니다.
디바이스가 404104 DeviceConnectionClosedRemotely와의 연결 끊기를 완료합니다.
IoT SDK는 새 SAS 토큰을 생성합니다.
디바이스가 IoT Hub와 다시 연결됨

또는 IoT Hub에서 인증 헤더, 규칙 또는 키를 인증할 수 없습니다. 이 결과는 현상에서 인용된 이유의 어떤 때문일 수 있습니다.

이 오류를 해결하려면 디바이스 연결 문자열을 사용하여 연결에 IoT SDK를 사용하는 경우 아무 작업도 필요하지 않습니다. IoT SDK는 새 토큰을 다시 생성하여 SAS 토큰 만료 시 다시 연결합니다.

기본 토큰 수명은 SDK에서 60분입니다. 그러나 일부 SDK의 경우 토큰 수명과 토큰 갱신 임계값을 구성할 수 있습니다. 또한 디바이스의 연결이 끊어지고 토큰 갱신 시 다시 연결될 때 발생하는 오류는 각 SDK마다 다릅니다. 자세한 내용과 디바이스가 로그에서 사용하는 SDK를 확인하는 방법에 대한 자세한 내용은 Azure IoT Hub 디바이스 연결 모니터링, 진단 및 문제 해결의 Azure IoT SDK 섹션을 사용하여 MQTT 디바이스 연결 끊기 동작을 참조하세요.

디바이스 개발자의 경우 오류 볼륨이 중요한 경우 만료 전에 SAS 토큰을 갱신하는 C SDK로 전환합니다. AMQP의 경우 SAS 토큰은 연결 끊김 없이 새로 고칠 수 있습니다.

일반적으로 표시되는 오류 메시지는 오류를 해결하는 방법을 설명해야 합니다. 어떤 이유로 오류 메시지 세부 사항에 액세스할 수 없는 경우 다음을 확인합니다.

사용하는 SAS 또는 기타 보안 토큰은 만료되지 않습니다.
X.509 인증서 인증의 경우 디바이스 인증서 또는 디바이스와 연결된 CA 인증서가 만료되지 않습니다. IoT Hub에 X.509 CA 인증서를 등록하는 방법을 알아보려면 자습서: 테스트를 위한 인증서 만들기 및 업로드를 참조하세요.
X.509 인증서 지문 인증의 경우 디바이스 인증서의 지문이 IoT Hub에 등록됩니다.
권한 부여 자격 증명은 사용하는 프로토콜에 대해 잘 구성됩니다. 자세한 내용은 Microsoft Entra ID를 사용하여 IoT Hub에 대한 액세스 제어를 참조하세요.
사용된 권한 부여 규칙에는 요청된 작업에 대한 권한이 있습니다.
"보안 주체..."로 시작하는 마지막 오류 메시지의 경우 사용자에게 올바른 수준의 Azure RBAC 권한을 할당하여 이 오류를 해결할 수 있습니다. 예를 들어 IoT Hub의 소유자는 모든 권한을 부여하는 "IoT Hub 데이터 소유자" 역할을 할당할 수 있습니다. 권한 부족 문제를 해결하려면 이 역할을 시도하세요.

비고

일부 디바이스는 디바이스 시간이 5분보다 큰 서버 시간과 차이가 있을 때 시간 드리프트 문제가 발생할 수 있습니다. 이 오류는 디바이스가 몇 주 또는 몇 달 동안 문제 없이 IoT Hub에 연결했지만 계속해서 연결을 거부하기 시작할 때 발생할 수 있습니다. 디바이스가 처음 연결되거나 켜진 시기에 따라 시간 드리프트가 다른 속도로 발생할 수 있으므로 이 오류는 IoT Hub에 연결된 디바이스의 하위 집합과 관련이 있을 수도 있습니다.

종종 NTP를 사용하여 시간 동기화를 수행하거나 부팅 시퀀스 중에 시간 동기화를 자동으로 수행할 수 있는 디바이스를 다시 부팅하면 문제가 해결되고 디바이스가 다시 연결할 수 있습니다. 이 오류를 방지하려면 NTP를 사용하여 정기적인 시간 동기화를 수행하도록 디바이스를 구성합니다. 디바이스 환경의 드리프트 양에 따라 매일, 매주 또는 매월 동기화를 예약할 수 있습니다. 디바이스에서 정기적인 NTP 동기화를 구성할 수 없는 경우 정기적인 재부팅을 예약합니다.

403002 IoT Hub 할당량 초과

IoT Hub에 대한 요청이 403002 IoTHubQuotaExceeded 오류로 실패할 수 있습니다. 또한 Azure Portal에서 IoT Hub 디바이스 목록은 로드되지 않습니다.

이 오류는 일반적으로 IoT Hub의 일일 메시지 할당량을 초과할 때 발생합니다. 이 오류를 해결하려면 다음을 수행합니다.

IoT Hub의 단위 수를 업그레이드하거나 늘리 거나 일일 할당량이 새로 고쳐질 때까지 다음 UTC 일을 기다립니다.
쌍 쿼리 및 직접 메서드와 같은 작업이 할당량에 계산되는 방식을 이해하려면 Azure IoT Hub 청구 정보의 작업당 요금 섹션을 참조하세요.
일일 할당량 사용량에 대한 모니터링을 설정하려면 사용된 총 메시지 수 메트릭을 사용하여 경고를 설정합니다. 단계별 지침은 자습서의 메트릭 설정 섹션을 참조하세요. IoT Hub에서 메트릭 및 로그 설정 및 사용

IoT Hub에 등록된 디바이스 수가 IoT Hub에 대한 할당량 한도를 초과하거나 접근하면 대량 가져오기 작업이 이 오류를 반환할 수도 있습니다. 자세한 내용은 IoT Hub 디바이스 ID 가져오기 및 내보내기의 가져오기 작업 문제 해결 섹션을 참조하세요.

403004 디바이스 최대 큐 깊이 초과

클라우드-디바이스 메시지를 보내려고 할 때 오류 403004 또는 DeviceMaximumQueueDepthExceeded와 함께 요청이 실패하는 것을 볼 수 있습니다.

이 오류의 근본 원인은 디바이스에 큐에 넣은 메시지 수가 큐 제한을 초과하기 위해서입니다.

이 제한에 도달할 가능성이 가장 큰 이유는 HTTPS를 사용하여 메시지를 수신하기 때문이며, 이로 인해 연속 폴링이 발생하여 ReceiveAsyncIoT Hub가 요청을 제한합니다.

HTTPS를 사용하는 클라우드-디바이스 메시지에 대해 지원되는 패턴은 메시지를 자주 확인하지 않는 간헐적으로 연결된 디바이스입니다(25분 미만). 대기열 제한에 도달할 가능성을 줄이려면 클라우드로부터 디바이스로의 메시지에 대해 AMQP 또는 MQTT로 프로토콜을 전환하세요.

또는 대기 중 메시지를 신속하게 완료, 거부 또는 중단하도록 디바이스 쪽 논리를 향상시키거나, 라이브 시간을 단축하거나, 메시지를 더 적게 보내는 것이 좋습니다. 자세한 내용은 IoT Hub에서 클라우드-디바이스 메시징 이해의 메시지 만료(TTL(수명 시간)) 섹션을 참조하세요.

마지막으로 큐 제거 API 를 사용하여 제한에 도달하기 전에 보류 중인 메시지를 주기적으로 정리하는 것이 좋습니다.

403006 디바이스 최대 활성 파일 업로드 제한을 초과했습니다.

DeviceMaximumActiveFileUploadLimitExceeded에 403006 오류 코드와 "활성 파일 업로드 요청 수가 10을 초과할 수 없습니다"라는 메시지와 함께 파일 업로드 요청이 실패하는 것을 볼 수 있습니다.

이 오류는 각 디바이스 클라이언트가 동시 파일 업로드에 대해 제한되기 때문에 발생합니다. 파일 업로드가 완료될 때 디바이스가 IoT Hub에 알리지 않으면 제한을 쉽게 초과할 수 있습니다. 신뢰할 수 없는 디바이스 쪽 네트워크는 일반적으로 이 문제를 일으킵니다.

이 오류를 해결하려면 디바이스가 IoT Hub 파일 업로드 완료를 즉시 알릴 수 있는지 확인합니다. 그런 다음 파일 업로드 구성을 위해 SAS 토큰 TTL을 줄여 보세요.

404001 디바이스를 찾을 수 없음

C2D 메시지, 트윈 업데이트 또는 직접 메서드와 같은 C2D(클라우드-장치) 통신 중에 404001 DeviceNotFound 오류로 인해 작업이 실패하는 경우가 있을 수 있습니다.

IoT Hub에서 디바이스를 찾을 수 없어 작업이 실패했습니다. 디바이스가 등록되지 않았거나 사용하지 않도록 설정되어 있습니다.

이 오류를 해결하려면 사용한 디바이스 ID를 등록한 다음 다시 시도합니다.

404103 디바이스가 온라인 상태가 아님

디바이스가 온라인 상태인 경우에도 DeviceNotOnline에 404103 오류와 함께 디바이스에 대한 직접 메서드가 실패하는 것을 볼 수 있습니다.

디바이스가 온라인 상태이고 여전히 오류가 발생하는 경우 직접 메서드 콜백이 디바이스에 등록되지 않았기 때문에 오류가 발생할 수 있습니다.

직접 메서드 콜백을 위해 디바이스를 올바르게 구성하는 방법에 대한 자세한 내용은 디바이스에서 직접 메서드 처리 섹션의 디바이스에서 직접 메서드 처리 섹션을 참조하세요.

404104 디바이스 연결이 원격으로 닫힘

디바이스가 정기적으로(예: 65분마다) 연결이 끊어지고 IoT Hub 리소스 로그에 deviceConnectionClosedRemotely 404104 표시될 수 있습니다. 경우에 따라 401003 IoTHubUnauthorized 및 성공적인 디바이스 연결 이벤트가 1분도 채 지나지 않아 표시됩니다.

또는 디바이스가 임의로 연결을 끊고 IoT Hub 리소스 로그에 DeviceConnectionClosedRemotely 404104 표시됩니다.

또는 많은 디바이스가 한 번에 연결이 끊기고, 연결된 디바이스(connectedDeviceCount) 메트릭이 급격히 감소하며, Azure Monitor 로그에서 평소보다 404104 DeviceConnectionClosedRemotely 및 500xxx 내부 오류가 더 많이 발생합니다.

이 오류는 IoT Hub에 연결하는 데 사용되는 SAS 토큰 이 만료되어 IoT Hub가 디바이스 연결을 끊기 때문에 발생할 수 있습니다. 디바이스에서 토큰을 새로 고치면 연결이 다시 설정됩니다. 예를 들어 SAS 토큰은 기본적으로 C SDK에 대해 매시간 만료되며, 이로 인해 정기적으로 연결이 끊어질 수 있습니다. 자세한 내용은 401003 IoTHubUnauthorized를 참조하세요.

몇 가지 다른 가능성은 다음과 같습니다.

디바이스가 MQTT 연결 유지보다 더 오래 기본 네트워크 연결을 끊어 원격 유휴 시간 제한이 발생합니다. MQTT 연결 유지 설정은 디바이스별로 다를 수 있습니다.
디바이스는 TCP/IP 수준 재설정을 보냈지만 애플리케이션 수준을 MQTT DISCONNECT보내지 않았습니다. 기본적으로 디바이스가 기본 소켓 연결을 갑자기 닫습니다. 경우에 따라 이전 버전의 Azure IoT SDK의 버그로 인해 이 문제가 발생할 수 있습니다.
디바이스 쪽 애플리케이션이 충돌했습니다.

또는 IoT Hub에 일시적인 문제가 발생할 수 있습니다. 자세한 내용은 500xxx 내부 오류를 참조하세요.

이 오류를 해결하려면 다음을 수행합니다.

오류 401003 IoTHubUnauthorized에 대한 지침을 참조하세요.
연결을 테스트하여 디바이스가 IoT Hub에 제대로 연결되어 있는지 확인합니다. 네트워크가 불안정하거나 간헐적인 경우 탐지(예: Azure Monitor 경고를 통해)가 더 오래 걸리는 결과를 초래할 수 있으므로, 연결 유지 값을 증가시키지 않는 것이 좋습니다.
최신 버전의 Azure IoT Hub SDK를 사용합니다.
500xxx 내부 오류에 대한 지침을 참조하세요.

비고

Azure IoT 디바이스 SDK를 사용하여 연결을 신뢰할 수 있도록 관리하는 것이 좋습니다. 자세한 내용은 디바이스 재연결 관리를 통해 복원력 있는 애플리케이션을 만드는 방법을 참조하세요.

409001 디바이스가 이미 있음

IoT Hub에서 디바이스를 등록하려고 할 때 DeviceAlreadyExists에 409001 오류와 함께 요청이 실패하는 것을 볼 수 있습니다.

이 오류는 IoT Hub에 동일한 디바이스 ID를 가진 디바이스가 이미 있기 때문에 발생합니다.

이 오류를 해결하려면 다른 디바이스 ID를 사용하고 다시 시도합니다.

링크 만들기 충돌 409002

디바이스 연결 끊기 또는 클라우드-디바이스 메시지 오류와 함께 로그에 LinkCreationConflict 409002 오류가 표시될 수 있습니다.

일반적으로 이 오류는 IoT Hub가 클라이언트에 둘 이상의 연결이 있는 것을 감지할 때 발생합니다. 실제로 기존 연결이 있는 디바이스에 대한 새 연결 요청이 도착하면 IoT Hub는 이 오류로 기존 연결을 닫습니다.

가장 일반적인 경우 별도의 문제(예: 404104 DeviceConnectionClosedRemotely)로 인해 디바이스의 연결이 끊어집니다. 디바이스는 연결을 즉시 다시 설정하려고 하지만 IoT Hub는 여전히 연결된 디바이스를 고려합니다. IoT Hub는 이전 연결을 닫고 이 오류를 기록합니다.

또는 디바이스 쪽 논리가 잘못되면 디바이스가 이미 열려 있을 때 연결이 설정됩니다.

이 오류를 해결하려면 이 오류가 일반적으로 다른 일시적인 문제의 부작용으로 표시되므로 문제를 해결할 수 있는 다른 오류를 로그에서 찾습니다. 그렇지 않으면 연결이 끊어질 때만 새 연결 요청을 실행해야 합니다.

412002 디바이스 메시지 잠금 손실

클라우드-디바이스 메시지를 보내려고 할 때 DeviceMessageLockLost에 412002 오류와 함께 요청이 실패하는 것을 볼 수 있습니다.

이 오류는 디바이스가 큐에서 클라우드-디바이스 메시지를 수신할 때(예: 사용 ReceiveAsync()) IoT Hub가 1분의 잠금 시간 제한 기간 동안 메시지를 잠그기 때문에 발생합니다. 잠금 제한 시간이 만료된 후 디바이스가 메시지를 완료하려고 하면 IoT Hub에서 이 예외를 throw합니다.

IoT Hub가 1분 잠금 시간 제한 기간 내에 알림을 받지 못하면 메시지를 큐에 추가 된 상태로 다시 설정합니다. 디바이스가 메시지를 다시 수신하려고 시도할 수 있습니다. 나중에 오류가 발생하지 않도록 하려면 디바이스 쪽 논리를 구현하여 메시지를 받은 후 1분 이내에 메시지를 완료합니다. 이 1분 제한 시간은 변경할 수 없습니다.

429xxx 스로틀링 예외

다음과 같이 429 로 시작하는 오류로 IoT Hub에 대한 요청이 실패할 수 있습니다.

429000 - 너무 많은 요청 (GenericTooManyRequests)
429001 – ThrottlingException: 요청된 작업에 대한 제한 제한이 초과되었습니다.
429002 - ThrottleBacklogLimitExceeded: 스로틀링으로 인해 백로그에 있는 요청 수가 백로그 제한을 초과했습니다.
429003 - ThrottlingBacklogTimeout: 백로그 큐에서 기다리는 동안 제한으로 인해 백로그된 요청의 시간이 초과되었습니다.
429004 - 제한 설정 최대 활성 작업 수 초과됨
429005 – 기기 제한 초과

Azure Monitor에서 메트릭 제한 오류 수 아래에서만 429001을 모니터링할 수 있습니다. 현재 다른 제한 오류에는 연결된 메트릭이 없지만 로그에 캡처됩니다.

이러한 오류를 해결하려면 원격 분석 메시지 보내기 시도 메트릭을 이전에 지정한 제한과 비교하여 제한 한도에 도달했는지 확인합니다. 스로틀링 오류 수 메트릭을 확인할 수도 있습니다. 이러한 메트릭에 대한 자세한 내용은 디바이스 원격 분석 메트릭을 참조하세요. 메트릭을 사용하여 IoT Hub를 모니터링하는 방법에 대한 자세한 내용은 Azure IoT Hub 모니터링을 참조하세요.

IoT Hub는 너무 오랫동안 제한을 위반한 후에만 429001 – ThrottlingException 을 반환합니다. 이 지연은 IoT Hub가 버스트 트래픽을 가져오는 경우 메시지가 삭제되지 않도록 수행됩니다. 반면 IoT Hub는 작업 제한 속도로 메시지를 처리합니다. 이 경우에 백로그에 너무 많은 트래픽이 있으면 성능이 저하될 수 있습니다. 자세한 내용은 IoT Hub 할당량 및 제한의 트래픽 셰이핑 섹션을 참조하세요.

할당량 또는 제한 한도에 도달하는 경우 IoT 허브를 스케일 업하는 것이 좋습니다.

500xxx 내부 오류

500 및/또는 일종의 "서버 오류"로 시작하는 오류로 IoT Hub에 대한 요청이 실패할 수 있습니다. 몇 가지 가능성은 다음과 같습니다.

500001 ServerError: IoT Hub에서 서버 쪽 문제가 발생했습니다.
500008 GenericTimeout: IoT Hub가 시간 초과 전에 연결 요청을 완료할 수 없습니다.
ServiceUnavailable(오류 코드 없음): IoT Hub에서 내부 오류가 발생했습니다.
InternalServerError(오류 코드 없음) : IoT Hub에서 내부 오류가 발생했습니다.

500xxx 오류 응답에는 여러 가지 원인이 있을 수 있습니다. 모든 경우에 이 문제는 일시적일 가능성이 큽니다. IoT Hub 팀은 SLA를 유지하기 위해 열심히 노력하지만, IoT Hub 노드의 작은 하위 집합에서 일시적인 오류가 발생할 수 있습니다. 디바이스에서 문제가 있는 노드에 연결하려고 하면 이 오류가 발생합니다.

500xxx 오류를 완화하려면 디바이스에서 다시 시도를 실행합니다. 재시도를 자동으로 관리하려면 최신 버전의 Azure IoT Hub SDK를 사용해야 합니다. 일시적인 오류 처리 및 재시도 모범 사례에 대한 자세한 내용은 일시적인 오류 처리를 참조하세요.

문제가 지속되면 Resource Health 및 Azure 상태를 확인하여 IoT Hub에 알려진 문제가 있는지 확인합니다. 수동 장애 조치(failover) 기능을 사용할 수도 있습니다.

알려진 문제가 없고 문제가 계속되면 추가 조사를 위해 지원에 문의하세요 .

503003 파티션을 찾을 수 없음

PartitionNotFound에 503003 오류로 IoT Hub에 대한 요청이 실패하는 것을 볼 수 있습니다.

이 오류는 IoT Hub 내부이며 일시적일 수 있습니다. 자세한 내용은 500xxx 내부 오류를 참조하세요.

이 오류를 해결하려면 500xxx 내부 오류를 참조하세요.

504101 게이트웨이 시간 초과

IoT Hub에서 디바이스로 직접 메서드를 호출하려고 하면 GatewayTimeout에 504101 오류와 함께 요청이 실패하는 것을 볼 수 있습니다.

이 오류는 IoT Hub에 오류가 발생하여 시간 초과 전에 직접 메서드가 완료되었는지 확인할 수 없기 때문에 발생합니다. 또는 이전 버전의 Azure IoT C# SDK(<1.19.0)를 사용하는 경우 버그로 인해 디바이스와 IoT Hub 간의 AMQP 링크를 자동으로 삭제할 수 있습니다.

이 오류를 해결하려면 다시 시도하거나 최신 버전의 Azure IOT C# SDK로 업그레이드합니다.