이 페이지는 Cloud Translation API를 통해 번역되었습니다.

500 내부 서버 오류

현재 Apigee Edge 문서가 표시되고 있습니다.
Apigee X 문서로 이동 정보

동영상

내부 서버 오류 500개를 해결하는 방법에 대해 자세히 알아보려면 다음 동영상을 시청하세요.

동영상	설명
소개	500개의 내부 서버 오류와 가능한 원인을 소개합니다. 또한 실시간 500 내부 서버 오류와 오류 해결 단계를 보여줍니다.
서비스 콜아웃 및 변수 추출 오류 처리	서비스 콜아웃 및 변수 추출 정책으로 인해 발생한 500 내부 서버 오류 2개를 보여주고 이러한 오류를 해결하는 방법을 보여줍니다.
자바스크립트 정책 오류 처리	JavaScript 정책으로 인해 발생한 500 내부 서버 오류와 문제 해결 단계가 표시됩니다.
백엔드 서버의 오류 처리	백엔드 서버 실패로 인해 발생한 500개의 내부 서버 오류 예시와 오류 해결 단계를 보여줍니다.

증상

클라이언트 애플리케이션은 API 호출에 대한 응답으로 "Internal Server Error"라는 메시지와 함께 HTTP 상태 코드 500을 가져옵니다. 500 내부 서버 오류는 Edge 내에서 정책을 실행하는 동안 오류가 발생하거나 대상/백엔드 서버의 오류로 인해 발생할 수 있습니다.

HTTP 상태 코드 500은 일반적인 오류 응답입니다. 이는 서버에 요청을 수행할 수 없는 예기치 않은 상황이 발생했음을 의미합니다. 이 오류는 일반적으로 다른 오류 코드가 적합하지 않은 경우 서버에서 반환됩니다.

오류 메시지

다음과 같은 오류 메시지가 표시될 수 있습니다.

HTTP/1.1 500 Internal Server Error

경우에 따라 더 자세한 내용이 포함된 다른 오류 메시지가 표시될 수도 있습니다. 다음은 샘플 오류 메시지입니다.

{
   "fault":{
      "detail":{
         "errorcode":"steps.servicecallout.ExecutionFailed"
      },
      "faultstring":"Execution of ServiceCallout callWCSAuthServiceCallout failed. Reason: ResponseCode 400 is treated as error"
   }
}

가능한 원인

500 내부 서버 오류는 다양한 원인으로 발생할 수 있습니다. Edge에서 원인은 오류가 발생한 위치에 따라 두 가지 주요 카테고리로 분류할 수 있습니다.

원인	세부정보	자세한 문제 해결 단계 제공
에지 정책의 실행 오류	API 프록시 내의 Policy가 어떤 이유로든 실패할 수 있습니다.	에지 프라이빗 및 퍼블릭 클라우드 사용자
백엔드 서버에 발생하는 오류	백엔드 서버가 어떤 이유로 실패할 수 있습니다.	에지 프라이빗 및 퍼블릭 클라우드 사용자

에지 정책의 실행 오류

API 프록시 내의 Policy가 어떤 이유로든 실패할 수 있습니다. 이 섹션에서는 정책 실행 중에 500 내부 서버 오류가 발생하는 경우 문제를 해결하는 방법을 설명합니다.

진단

프라이빗 및 퍼블릭 클라우드 사용자를 위한 진단 단계

오류에 대한 트레이스 UI 세션이 있는 경우 다음과 같습니다.

오류가 정책 실행으로 인해 발생한 것인지 확인합니다. 자세한 내용은 문제의 원인 파악을 참조하세요.
정책 실행 중에 오류가 발생하면 계속 진행하세요. 백엔드 서버로 인해 오류가 발생한 경우 백엔드 서버 오류로 이동합니다.
추적에서 500 내부 서버 오류와 함께 실패한 API 요청을 선택합니다.
요청을 살펴보고 실패한 특정 정책 또는 트레이스에서 실패한 정책 바로 다음에 오는 'Error'라는 흐름을 선택합니다.
속성 섹션의 '오류' 필드 또는 오류 콘텐츠를 확인하여 오류에 대한 자세한 내용을 확인하세요.
오류에 대해 수집한 세부정보를 사용하여 원인을 파악해 보세요.

프라이빗 클라우드 사용자만을 위한 진단 단계

트레이스 UI 세션이 없는 경우 다음을 실행하세요.

정책 실행 중에 오류가 발생했는지 확인합니다. 자세한 내용은 문제의 원인 파악을 참조하세요.
정책 실행으로 인해 오류가 발생한 경우 계속 진행합니다. 정책 실행 중에 오류가 발생하면 계속 진행하세요. 백엔드 서버로 인해 오류가 발생한 경우 백엔드 서버 오류로 이동합니다.
문제의 원인 확인에 설명된 대로 NGINX 액세스 로그를 사용하여 API 프록시의 실패한 정책과 고유 요청 메시지 ID를 확인합니다.
메시지 프로세서 로그(/opt/apigee/var/log/edge-message-processor/logs/system.log)를 확인하고 그 안에서 고유한 요청 메시지 ID를 검색합니다.
고유한 요청 메시지 ID를 찾으면 실패 원인에 대한 추가 정보를 얻을 수 있는지 확인합니다.

해상도

정책 문제의 원인을 파악했다면 정책을 수정하고 프록시를 다시 배포하여 문제를 해결해 보세요.

다음 예는 다양한 문제 유형의 원인과 해결 방법을 확인하는 방법을 보여줍니다.

500 내부 서버 오류 문제 해결을 위해 추가 지원이 필요하거나 Edge 내에서 이 문제가 발생한 것으로 의심되면 Apigee 지원팀에 문의하세요.

예 1: 백엔드 서버의 오류로 인해 서비스 콜아웃 정책 실패

서비스 콜아웃 정책 내에서 백엔드 서버 호출이 4XX 또는 5XX와 같은 오류와 함께 실패하면 500 내부 서버 오류로 처리됩니다.

다음은 서비스 콜아웃 정책 내에서 404 오류로 백엔드 서비스가 실패하는 예입니다. 다음 오류 메시지가 최종 사용자에게 전송됩니다.

{
"fault":
     { "detail":
           { "errorcode":"steps.servicecallout.ExecutionFailed"
           },"faultstring":"Execution of ServiceCallout service_callout_v3_store_by_lat_lon
 failed. Reason: ResponseCode 404 is treated as error"
          }
     }
}

다음 트레이스 UI 세션은 서비스 콜아웃 정책의 오류로 인해 발생한 500 상태 코드를 보여줍니다.
이 예에서 'error' 속성은 서비스 콜아웃 정책 실패의 이유를 'ResponseCode 404 is error as error'로 나열합니다. 이 오류는 서비스 콜아웃 정책의 백엔드 서버 URL을 통해 리소스에 액세스하는 경우에 발생할 수 있습니다.
백엔드 서버에서 리소스를 사용할 수 있는지 확인합니다. 일시적으로 또는 영구적으로 사용할 수 없거나 다른 위치로 이동했을 수 있습니다.

예 1 해결 방법

백엔드 서버에서 리소스를 사용할 수 있는지 확인합니다. 일시적으로 또는 영구적으로 사용할 수 없거나 다른 위치로 이동했을 수 있습니다.
유효한 기존 리소스를 가리키도록 서비스 콜아웃 정책의 백엔드 서버 URL을 수정합니다.
리소스를 일시적으로 사용할 수 없는 경우에는 리소스를 사용할 수 있게 되었을 때 API를 요청해 보세요.

예 2: 변수 추출 정책 실패

변수 추출 정책의 오류로 인해 500 내부 서버 오류가 발생하는 또 다른 예를 살펴보고 문제 해결 방법을 살펴보겠습니다.

UI 세션의 다음 trace는 변수 추출 정책의 오류로 인해 500 상태 코드를 보여줍니다.
실패한 변수 추출 정책을 선택하고 아래로 스크롤한 후 '오류 콘텐츠' 섹션에서 자세한 내용을 확인합니다.
오류 콘텐츠는 변수 추출 정책에서 "service callout.oamCookieValidationResponse" 변수를 사용할 수 없음을 나타냅니다. 변수 이름에 표시된 것처럼 이전 서비스 콜아웃 정책의 응답이 있어야 합니다.
추적에서 서비스 콜아웃 정책을 선택하면 'serviceCallout.oamCookieValidationResponse' 변수가 설정되지 않은 것을 확인할 수 있습니다. 이는 백엔드 서비스 호출이 실패하여 응답 변수가 비어 있음을 나타냅니다.

서비스 콜아웃 정책은 실패했지만, 아래와 같이 서비스 콜아웃 정책의 'continueOnError' 플래그가 true로 설정되어 있으므로 서비스 콜아웃 정책 이후의 정책 실행은 계속됩니다.

<ServiceCallout async="false" continueOnError="true" enabled="true" name="Callout.OamCookieValidation">
  <DisplayName>Callout.OamCookieValidation</DisplayName>
  <Properties />
  <Request clearPayload="true" variable="serviceCallout.oamCookieValidationRequest">
    <IgnoreUnresolvedVariables>false</IgnoreUnresolvedVariables>
  </Request>
  <Response>serviceCallout.oamCookieValidationResponse</Response>
  <HTTPTargetConnection>
    <Properties />
    <URL>http://{Url}</URL>
  </HTTPTargetConnection>
</ServiceCallout>

다음과 같이 트레이스에서 특정 API 요청에 대한 고유한 메시지 ID "X-Apigee.Message-ID"를 확인합니다.
1. 요청에서 '기록된 애널리틱스 데이터' 단계를 선택합니다.
2. 아래로 스크롤하여 X-Apigee.Message-ID 값을 확인합니다.
참고: 다음 단계는 Edge Private Cloud 사용자만 수행할 수 있습니다.
메시지 프로세서 로그(/opt/apigee/var/log/edge-message-processor/system.log)를 확인하고 6단계에서 기록한 고유한 메시지 ID를 검색합니다. 특정 API 요청에서 다음과 같은 오류 메시지가 발견되었습니다.
```
2017-05-05 07:48:18,653 org:myorg env:prod api:myapi rev:834 messageid:rrt-04984fed9e5ad3551-c-wo-32168-77563  NIOThread@5 ERROR HTTP.CLIENT - HTTPClient$Context.onTimeout() : ClientChannel[C:]@149081 useCount=1 bytesRead=0 bytesWritten=0 age=3002ms lastIO=3002ms .onConnectTimeout connectAddress=mybackend.domain.com/XX.XX.XX.XX:443 resolvedAddress=mybackend.domain.com/XX.XX.XX.XX
```
위 오류는 백엔드 서버에 연결하는 동안 연결 시간 초과 오류로 인해 서비스 콜아웃 정책이 실패했음을 나타냅니다.
연결 시간 초과 오류의 원인을 파악하기 위해 메시지 프로세서에서 백엔드 서버에 대해 telnet 명령어를 실행했습니다. telnet 명령어에서 아래와 같이 '연결 시간이 초과되었습니다' 오류가 발생했습니다.
```
telnet mybackend.domain.com 443
Trying XX.XX.XX.XX...
telnet: connect to address XX.XX.XX.XX: Connection timed out
```
일반적으로 이 오류는 다음과 같은 경우에 나타납니다.
- 백엔드 서버가 에지 메시지 프로세서의 트래픽을 허용하도록 구성되지 않은 경우
- 백엔드 서버가 특정 포트에서 리슨하지 않는 경우
위의 예시에서 변수 추출 정책에 실패했지만 실제 원인은 Edge가 서비스 콜아웃 정책에서 백엔드 서버에 연결할 수 없기 때문입니다. 이 오류가 발생한 이유는 백엔드 최종 서버가 에지 메시지 프로세서의 트래픽을 허용하도록 구성되지 않았기 때문입니다.

자체 변수 추출 정책은 다르게 작동하며 다른 이유로 실패할 수 있습니다. error 속성에서 메시지를 확인하여 변수 추출 정책의 실패 원인에 따라 문제를 적절하게 해결할 수 있습니다.

예 2 해결 방법

변수 추출 정책에서 오류 또는 실패의 원인을 적절하게 수정합니다.
위의 그림에서 이 해결책은 에지 메시지 프로세서에서 백엔드 서버로의 트래픽을 허용하도록 네트워크 구성을 수정하는 것이었습니다. 이 작업은 특정 백엔드 서버에서 메시지 프로세서의 IP 주소를 허용 목록에 추가하는 방식으로 수행되었습니다. 예를 들어 Linux에서는 iptables를 사용하여 백엔드 서버에 있는 메시지 프로세서의 IP 주소에서 오는 트래픽을 허용할 수 있습니다.

예 3: JavaCall 정책 실패

이제 자바 콜아웃 정책의 오류로 인해 500 내부 서버 오류가 발생하는 예를 하나 더 살펴보고 문제를 해결하는 방법을 살펴보겠습니다.

다음 UI 추적은 Java 콜아웃 정책의 오류로 인해 500 상태 코드를 보여줍니다.
아래 그림과 같이 "Error"라는 흐름에 이어 실패한 자바 콜아웃 정책을 선택하여 오류 세부정보를 가져옵니다.
이 예시에서 속성 섹션의 "error" 속성은 자바 콜아웃 정책 내에서 Oracle 데이터베이스에 연결하는 동안 만료된 비밀번호 사용으로 인해 실패했음을 보여줍니다. 자체 자바 콜아웃은 다르게 동작하며 error 속성에 다른 메시지를 채웁니다.
Java콜아웃 정책 코드를 확인하고 사용해야 하는 올바른 구성이 있는지 확인하세요.

예 3 해결 방법

자바 콜아웃 코드 또는 구성을 적절하게 수정하여 런타임 예외를 방지합니다. 위의 자바 콜아웃 실패 예시에서 문제를 해결하려면 올바른 비밀번호를 사용하여 Oracle 데이터베이스에 연결해야 합니다.

백엔드 서버의 오류

500 내부 서버 오류는 백엔드 서버에서도 발생할 수 있습니다. 이 섹션에서는 백엔드 서버에서 오류가 발생하는 경우 문제를 해결하는 방법을 설명합니다.

진단

모든 사용자를 위한 진단 단계

기타 백엔드 오류의 원인은 크게 다를 수 있습니다. 각 상황을 개별적으로 진단해야 합니다.

백엔드 서버로 인해 오류가 발생했는지 확인합니다. 자세한 내용은 문제의 원인 파악을 참조하세요.
백엔드 서버로 인해 오류가 발생한 경우 계속 진행합니다. 정책 실행 중에 오류가 발생하면 에지 정책 실행 오류로 이동하세요.
실패한 API의 Trace 세션에 액세스할 수 있는지 또는 백엔드가 Node.js 서버인지에 따라 다음 단계를 따르세요.

실패한 API 호출에 대한 추적 세션이 없는 경우:

실패한 요청에 UI 트레이스를 사용할 수 없으면 백엔드 서버 로그를 확인하여 오류에 대한 세부정보를 확인합니다.
가능하면 백엔드 서버에서 디버그 모드를 사용 설정하여 오류와 원인에 대한 세부정보를 확인하세요.

실패한 API 호출에 대한 추적 세션이 있는 경우:

Trace 세션이 있는 경우 다음 단계에 따라 문제를 진단할 수 있습니다.

추적 도구에서 500 내부 서버 오류와 함께 실패한 API 요청을 선택합니다.
아래 그림과 같이 실패한 API 요청에서 'Response received from target server' 단계를 선택합니다.
오류에 대한 자세한 내용은 '응답 콘텐츠' 섹션을 확인하세요.
이 예에서 응답 콘텐츠(SOAP 봉투)는 오류 문자열을 '승인되지 않음' 메시지로 표시합니다. 이 문제의 원인은 사용자가 올바른 사용자 인증 정보 (사용자 이름/비밀번호, 액세스 토큰 등)를 백엔드 서버에 전달하지 않았기 때문입니다. 이 문제는 올바른 사용자 인증 정보를 백엔드 서버에 전달하면 해결할 수 있습니다.

백엔드가 Node.js 서버인 경우:

백엔드가 Node.js 백엔드 서버인 경우 Edge UI에서 특정 API 프록시의 Node.js 로그를 확인합니다 (퍼블릭 및 프라이빗 클라우드 사용자 모두 Node.js 로그를 확인할 수 있음). Edge Private Cloud 사용자인 경우 메시지 프로세서 로그(/opt/apigee/var/log/edge-message-processor/logs/system.log)에서 오류에 대한 자세한 내용을 확인할 수도 있습니다.

Edge UI의 NodeJS 로그 옵션 - API 프록시의 개요 탭

해결 방법

오류의 원인을 파악했다면 백엔드 서버에서 문제를 해결합니다.
Node.js 백엔드 서버인 경우:
1. 커스텀 코드에서 오류가 발생했는지 확인하고 가능한 경우 문제를 해결합니다.
2. 커스텀 코드에서 오류가 발생하지 않거나 지원이 필요하면 Apigee 지원팀에 문의하세요.

500 내부 서버 오류 문제 해결을 위해 추가 지원이 필요하거나 Edge 내에서 이 문제가 발생한 것으로 의심되면 Apigee 지원팀에 문의하세요.

문제의 원인 파악

다음 절차 중 하나를 사용하여 API 프록시 내에서 또는 백엔드 서버에서 정책을 실행하는 동안 500 내부 서버 오류가 발생했는지 확인합니다.

UI에서 트레이스 사용

참고: 이 섹션의 단계는 퍼블릭 및 프라이빗 클라우드 사용자가 모두 수행할 수 있습니다.

문제가 아직 해결되지 않은 경우 UI에서 영향을 받은 API에 트레이스를 사용 설정합니다.
트레이스를 캡처한 후 응답 코드를 500으로 표시하는 API 요청을 선택합니다.
실패한 API 요청의 모든 단계를 살펴보고 500 내부 서버 오류를 반환하는 단계를 확인합니다.
1. 정책 실행 중에 오류가 발생하면 에지 정책의 실행 오류를 진행합니다.
2. 백엔드 서버가 500개의 내부 서버로 응답한 경우 백엔드 서버에 오류가 발생했습니다를 진행합니다.

API 모니터링 사용

참고: 이 섹션의 단계는 퍼블릭 클라우드 사용자만 수행할 수 있습니다.

API 모니터링을 사용하면 문제 영역을 빠르게 격리하여 오류, 성능, 지연 시간 문제를 진단하고 개발자 앱, API 프록시, 백엔드 대상, API 플랫폼 등 그 원인을 진단할 수 있습니다.

API 모니터링을 사용하여 API의 5xx 문제를 해결하는 방법을 보여주는 샘플 시나리오를 단계별로 살펴보세요. 예를 들어 상태 코드 500개 또는 steps.servicecallout.ExecutionFailed 오류 수가 특정 기준점을 초과하면 알림을 받도록 설정할 수 있습니다.

NGINX 액세스 로그 사용

참고: 이 섹션의 단계는 Edge Private Cloud 사용자만을 대상으로 합니다.

NGINX 액세스 로그를 참조하여 정책 실행 중에 API 프록시 내에서 또는 백엔드 서버에서 500 상태 코드가 발생했는지 확인할 수도 있습니다. 이 방법은 과거에 문제가 발생한 적이 있거나 문제가 간헐적으로 발생하고 UI에서 트레이스를 캡처할 수 없는 경우에 특히 유용합니다. NGINX 액세스 로그에서 이 정보를 확인하려면 다음 단계를 따르세요.

NGINX 액세스 로그 (/opt/apigee/var/log/edge-router/nginx/ <org>~ <env>.<port#>_access_log )를 확인합니다.
특정 기간 동안 특정 API 프록시에 오류 500개가 있는지 검색합니다.
오류가 500개 발생한 경우 아래와 같이 오류가 정책인지 대상 서버 오류인지 확인합니다.
정책 오류를 보여주는 샘플 항목

대상 서버 오류를 보여주는 샘플 항목
정책 또는 대상 서버 오류인지 확인한 후 다음 단계를 따릅니다.
1. 정책 오류인 경우 에지 정책 실행 오류로 이동합니다.
2. 대상 서버 오류인 경우 백엔드 서버 오류로 진행합니다.