응답 오류 문제해결

이 페이지에서는 API에 대한 요청의 응답에서 수신되는 오류의 문제해결 방법을 설명합니다.

Upstream backend unavailable

오류 코드 14와 upstream backend unavailable 메시지가 수신되면 Extensible Service Proxy(ESP)가 서비스의 백엔드에 연결할 수 없는 경우입니다. 다음을 확인하세요.

  • 백엔드 서비스가 실행 중인지 확인합니다. 수행 방법은 백엔드에 따라 달라집니다.

  • 백엔드 서비스의 올바른 IP 주소 포트가 지정되었는지 확인합니다.
    • GKE의 경우 배포 매니페스트 파일(일반적으로 deployment.yaml)에서 ESP --backend 플래그 값(단축 옵션은 -a)을 확인합니다.
    • Compute Engine의 경우 docker run 명령어로 ESP --backend 플래그 값(단축 옵션은 -a)을 확인합니다.

reset reason: connection failure

HTTP 코드 503 또는 gRPC 코드 14와 upstream connect error or disconnect/reset before headers. reset reason: connection failure 메시지를 받은 경우 ESPv2가 서비스의 백엔드에 연결할 수 없음을 나타냅니다.

문제를 해결하려면 아래 항목을 다시 확인하세요.

백엔드 주소

ESPv2를 올바른 백엔드 주소로 구성해야 합니다. 일반적인 문제는 다음과 같습니다.

  • 백엔드 주소 스키마는 백엔드 애플리케이션 유형과 일치해야 합니다. OpenAPI 백엔드는 http://이고 gRPC 백엔드는 grpc://여야 합니다.
  • Cloud Run에 배포된 ESPv2의 경우 백엔드 주소 스키마가 https:// 또는 grpcs://여야 합니다. s는 ESPv2에 백엔드로 TLS를 설정하도록 지시합니다.

DNS 조회

기본적으로 ESPv2는 도메인 이름을 IPv6 주소로 확인하려고 시도합니다. IPv6 확인이 실패하면 ESPv2가 IPv4 주소로 돌아갑니다.

일부 네트워크에서는 대체 메커니즘이 의도한 대로 작동하지 않을 수 있습니다. 대신 ESPv2가 --backend_dns_lookup_family 플래그를 통해 IPv4 주소를 사용하도록 강제할 수 있습니다.

이 오류는 Cloud Run에 배포된 ESPv2의 서버리스 VPC 커넥터를 구성하는 경우에 일반적으로 나타납니다. VPC는 IPv6 트래픽을 지원하지 않습니다.

API is not enabled for the project

요청에 API 키를 전송한 경우 'API my-api.endpoints.example-project-12345.cloud.goog가 프로젝트에 사용 설정되지 않았습니다.'와 같은 오류 메시지는 해당 API와 다른 Google Cloud 프로젝트에서 API 키를 만들었음을 나타냅니다. 이 문제를 해결하려면 API가 연결된 것과 동일한 Google Cloud 프로젝트에서 API 키를 생성하거나 API 키가 생성된 Google Cloud 프로젝트에서 API를 사용 설정하면 됩니다.

Service control request failed with HTTP response code 403

오류 코드 14와 Service control request failed with HTTP response code 403 메시지가 수신되면 프로젝트에서 Service Control API(servicecontrol.googleapis.com)가 사용 설정되지 않은 경우입니다.

  1. 필수 서비스 확인을 참조하여 Endpoints 및 ESP에 필요한 서비스가 프로젝트에서 모두 사용 설정되었는지 확인하세요.

  2. ESP 실행 인스턴스와 연관된 서비스 계정에 필요한 모든 권한을 확인하려면 필요한 권한 확인을 참조하세요.

Method doesn't allow unregistered callers

gRPC API 구성 파일에 allow_unregistered_calls: false를 지정했지만 API 요청에서 key라는 쿼리 매개변수에 API 키가 할당되어 있지 않으면 ESP가 Method doesn't allow unregistered callers 오류로 응답합니다.

API를 호출하기 위해 API 키를 생성해야 하는 경우 API 키 만들기를 참조하세요.

Method does not exist

Method does not exist 응답은 지정된 URL 경로에서 GET, POST 등의 HTTP 메서드를 찾을 수 없다는 의미입니다. 문제해결을 위해서는 배포한 서비스 구성을 비교하여 요청으로 전송 중인 메서드 이름과 URL 경로가 일치하는지 확인합니다.

  1. Google Cloud Console에서 프로젝트의 Endpoints 서비스 페이지로 이동합니다.

    Endpoints 서비스 페이지로 이동

  2. API가 2개 이상인 경우 요청을 전송한 API를 선택합니다.

  3. 배포 기록 탭을 클릭합니다.

  4. 최신 배포를 선택해서 서비스 구성을 확인합니다.

Transport is closing

오류 코드 13과 transport is closing 메시지가 수신되면 ESP에 연결할 수 없는 경우입니다.

ESP 오류 로그를 확인합니다. 수행 방법은 백엔드에 따라 달라집니다. 자세한 내용은 다음을 참조하세요.

예상치 못한 응답

HTTP 응답이 바이너리처럼 보인다면 요청이 HTTP1 포트를 사용하고자 했지만 HTTP2 포트를 사용하여 API에 접근하는 경우일 수 있습니다.

ESP의 포트 구성 옵션을 확인합니다. 단축 플래그 형태인 -p(HTTP1)와 -P(HTTP2)가 서로 비슷하므로 긴 플래그 형태인 --http_port(HTTP1)와 --http2_port(HTTP2)를 사용하는 것이 좋습니다.

ESP 백엔드 구성이 잘못되어 예상치 못한 응답이 발생할 수도 있습니다. 백엔드 플래그(-a 또는 --backend)가 gRPC URL(예: --backend=grpc://127.0.0.1:8081)로 설정되었는지 확인합니다.

ESP 플래그에 대한 자세한 내용은 ESP 시작 옵션을 참조하세요.

Cloud Logging 로그 확인

응답 오류 문제해결을 돕기 위해 Cloud Logging 로그를 사용하려면 다음 안내를 따르세요.

  1. Google Cloud Console에서 Logging 페이지로 이동합니다.

    로그 탐색기 페이지로 이동

  2. 페이지 상단에서 Google Cloud 프로젝트를 선택합니다.

  3. 왼쪽의 드롭다운 메뉴를 사용하여 생성된 API > [YOUR_SERVICE_NAME]을 선택합니다.

  4. 응답 오류가 표시되는 행이 보일 때까지 시간 범위를 조정합니다.

  5. JSON 페이로드를 확장하고 error_cause를 찾습니다.

    • error_cause가 application으로 설정된 경우 코드에서의 문제를 나타냅니다.

    • error cause가 다르고 문제를 해결할 수 없으면 로그를 내보내고 Google에 문의할 때 해당 로그를 보냅니다.

자세한 내용은 다음을 참조하세요.

  • 로그 탐색기에 표시되는 로그 구조에 대한 자세한 내용은 Endpoints 로그 참조를 참조하세요.

  • 로그 탐색기 사용 시작하기

  • 지연 시간이 300밀리초 이상인 모든 요청 가져오기 등 고급 필터링을 위해 고급 로그 쿼리를 사용합니다.