Oracle ORA-29273 오류 원인과 해결 방법 완벽 가이드

ORA-29273
2026년 10월 05일 | DBMS Error 가이드

이 글에서 다루는 내용

ORA-29273 에러의 원인 분석, 해결 SQL, 예방 방법을 실무 관점에서 정리합니다.

ORA-29273 HTTP request failed 는?

ORA-29273은 Oracle 데이터베이스 내에서 UTL_HTTP 패키지를 사용하여 외부 HTTP/HTTPS 요청을 보낼 때 해당 요청이 실패하면 발생하는 에러입니다. 이 에러는 Oracle 서버에서 외부 URL로의 네트워크 연결이 불가능하거나, 대상 서버의 응답이 없을 때, 또는 Oracle 내부 설정이 잘못되어 있을 때 주로 발생합니다. 특히 ERP 시스템, 외부 API 연동, 웹 서비스 호출 등 실무 환경에서 외부와의 통신이 필요한 PL/SQL 프로시저나 함수에서 자주 목격되는 에러입니다.

주요 발생 원인

1. ACL(Access Control List) 미설정 또는 잘못된 권한 구성

Oracle 11g 이후부터는 네트워크 접근에 대해 ACL(Access Control List) 기반의 보안 정책이 적용됩니다. 특정 데이터베이스 사용자가 외부 호스트로 HTTP 요청을 보내려면 반드시 해당 호스트에 대한 ACL 권한이 부여되어 있어야 하며, 이 권한이 없으면 즉시 ORA-29273 에러가 발생합니다. 많은 실무 환경에서 개발 단계에서는 권한을 부여해 놓고 운영 환경에 마이그레이션할 때 ACL 설정을 누락하는 경우가 빈번합니다.

2. 네트워크 방화벽 또는 프록시 설정 문제

Oracle 서버가 위치한 네트워크 환경에서 외부 인터넷 또는 특정 IP 대역으로의 아웃바운드 트래픽이 방화벽에 의해 차단될 경우 ORA-29273이 발생합니다. 기업 내부 네트워크에서는 보안 정책상 DB 서버에서 직접 외부로 나가는 포트(80, 443 등)를 막아두는 경우가 많기 때문에, 네트워크 팀과의 협업이 필요합니다. 프록시 서버를 통해야 하는 환경이라면 UTL_HTTP.SET_PROXY 설정도 함께 확인해야 합니다.

3. HTTPS SSL/TLS 인증서 문제 또는 Wallet 미설정

HTTPS 통신 시 Oracle은 SSL/TLS 인증서 검증을 수행하며, 이를 위해 Oracle Wallet이 올바르게 구성되어 있어야 합니다. Wallet이 설정되지 않았거나, 대상 서버의 SSL 인증서가 만료되었거나, 자체 서명 인증서(Self-Signed Certificate)를 신뢰하도록 등록하지 않은 경우에도 ORA-29273이 발생합니다. 이 원인은 특히 HTTPS 기반 REST API 연동 작업에서 자주 마주치며, 에러 메시지만으로는 구분하기 어렵기 때문에 상세 에러 추적이 필요합니다.

해결 방법

원인 1: ACL 권한 설정

Oracle 12c 이상에서는 DBMS_NETWORK_ACL_ADMIN 패키지를 사용하여 네트워크 ACL을 설정합니다.

-- ACL 생성 및 권한 부여 (Oracle 12c 이상)
BEGIN
  DBMS_NETWORK_ACL_ADMIN.APPEND_HOST_ACE(
    host    => 'api.example.com',   -- 접근할 외부 호스트
    lower_port => 443,              -- HTTPS 포트
    upper_port => 443,
    ace     => xs$ace_type(
                 privilege_list => xs$name_list('http'),
                 principal_name => 'YOUR_DB_USER',  -- DB 사용자명
                 principal_type => xs_acl.ptype_db
               )
  );
  COMMIT;
END;
/

-- ACL 설정 확인
SELECT host, lower_port, upper_port, ace_order,
       start_date, end_date, grant_option
FROM   dba_host_aces
WHERE  principal = 'YOUR_DB_USER'
ORDER  BY host;

-- Oracle 11g 방식 (구버전 호환)
BEGIN
  DBMS_NETWORK_ACL_ADMIN.CREATE_ACL(
    acl         => 'external_api_acl.xml',
    description => 'ACL for external API access',
    principal   => 'YOUR_DB_USER',
    is_grant    => TRUE,
    privilege   => 'connect'
  );

  DBMS_NETWORK_ACL_ADMIN.ASSIGN_ACL(
    acl  => 'external_api_acl.xml',
    host => 'api.example.com',
    lower_port => 80,
    upper_port => 443
  );
  COMMIT;
END;
/

원인 2: 프록시 설정 적용

방화벽 환경에서 프록시를 통해 외부 요청을 보내야 하는 경우 아래와 같이 설정합니다.

-- UTL_HTTP 프록시 설정 예시
DECLARE
  l_req   UTL_HTTP.REQ;
  l_resp  UTL_HTTP.RESP;
  l_text  VARCHAR2(32767);
BEGIN
  -- 프록시 서버 설정
  UTL_HTTP.SET_PROXY(
    proxy              => 'http://proxy.your-company.com:8080',
    no_proxy_domains   => 'internal.your-company.com'
  );

  -- HTTP GET 요청
  l_req  := UTL_HTTP.BEGIN_REQUEST(
               url    => 'https://api.example.com/data',
               method => 'GET'
            );
  UTL_HTTP.SET_HEADER(l_req, 'Content-Type', 'application/json');
  UTL_HTTP.SET_HEADER(l_req, 'Accept', 'application/json');

  l_resp := UTL_HTTP.GET_RESPONSE(l_req);

  LOOP
    UTL_HTTP.READ_TEXT(l_resp, l_text, 32767);
    DBMS_OUTPUT.PUT_LINE(l_text);
  END LOOP;

EXCEPTION
  WHEN UTL_HTTP.END_OF_BODY THEN
    UTL_HTTP.END_RESPONSE(l_resp);
  WHEN OTHERS THEN
    DBMS_OUTPUT.PUT_LINE('에러 발생: ' || SQLERRM);
    UTL_HTTP.END_RESPONSE(l_resp);
END;
/

원인 3: Oracle Wallet 설정 (HTTPS 전용)

HTTPS 통신을 위한 Oracle Wallet 생성 및 설정 절차입니다.

-- 1. OS 레벨에서 Wallet 생성 (터미널에서 실행)
-- orapki wallet create -wallet /opt/oracle/wallet -pwd WalletPassword123 -auto_login

-- 2. SSL 인증서 다운로드 후 Wallet에 추가
-- openssl s_client -connect api.example.com:443 -showcerts > /tmp/cert.pem
-- orapki wallet add -wallet /opt/oracle/wallet -trusted_cert -cert /tmp/cert.pem -pwd WalletPassword123

-- 3. Oracle DB에서 Wallet 경로 지정 후 HTTPS 요청
DECLARE
  l_wallet_path VARCHAR2(200) := 'file:/opt/oracle/wallet';
  l_wallet_pwd  VARCHAR2(200) := 'WalletPassword123';
  l_req         UTL_HTTP.REQ;
  l_resp        UTL_HTTP.RESP;
  l_buffer      VARCHAR2(32767);
BEGIN
  -- Wallet 설정
  UTL_HTTP.SET_WALLET(l_wallet_path, l_wallet_pwd);

  -- HTTPS 요청
  l_req := UTL_HTTP.BEGIN_REQUEST(
              url    => 'https://api.example.com/endpoint',
              method => 'POST'
           );

  UTL_HTTP.SET_HEADER(l_req, 'Content-Type', 'application/json');
  UTL_HTTP.SET_BODY_CHARSET('UTF-8');
  UTL_HTTP.WRITE_TEXT(l_req, '{"key":"value"}');

  l_resp := UTL_HTTP.GET_RESPONSE(l_req);
  DBMS_OUTPUT.PUT_LINE('HTTP Status: ' || l_resp.status_code || ' ' || l_resp.reason_phrase);

  BEGIN
    LOOP
      UTL_HTTP.READ_TEXT(l_resp, l_buffer, 32767);
      DBMS_OUTPUT.PUT_LINE(l_buffer);
    END LOOP;
  EXCEPTION
    WHEN UTL_HTTP.END_OF_BODY THEN NULL;
  END;

  UTL_HTTP.END_RESPONSE(l_resp);

EXCEPTION
  WHEN OTHERS THEN
    DBMS_OUTPUT.PUT_LINE('상세 에러: ' || SQLERRM);
    IF l_resp.private_hndl IS NOT NULL THEN
      UTL_HTTP.END_RESPONSE(l_resp);
    END IF;
END;
/

-- 현재 Wallet 설정 상태 확인
SELECT * FROM v$wallet;

-- 네트워크 서비스 접근 현황 확인
SELECT acl, host, lower_port, upper_port
FROM   dba_network_acls
ORDER  BY host;

예방 방법

1. 배포 체크리스트에 ACL 및 Wallet 설정 항목 포함

신규 외부 API 연동 기능을 개발하고 운영 환경에 배포할 때, ACL 권한 설정과 Oracle Wallet 인증서 등록이 배포 스크립트에 반드시 포함되도록 표준화된 체크리스트를 운영해야 합니다. 개발 DB와 운영 DB 간 환경 차이로 인해 개발 단계에서 정상 동작했던 기능이 운영에서 실패하는 사례를 줄일 수 있습니다. 또한 DBA_HOST_ACES, DBA_NETWORK_ACLS 뷰를 주기적으로 모니터링하여 권한 현황을 최신 상태로 유지하세요.

2. UTL_HTTP 호출 시 예외 처리 및 로깅 강화

모든 UTL_HTTP 호출 코드에는 반드시 상세한 예외 처리 블록을 포함시키고, 에러 발생 시 UTL_HTTP.GET_DETAILED_SQLERRM 함수를 사용하여 상세 에러 내용을 로그 테이블에 저장하도록 구현해야 합니다. 단순히 SQLERRM만 기록하는 것보다 훨씬 더 빠른 장애 대응이 가능하며, 정기적인 로그 검토를 통해 잠재적인 연결 불안정 문제를 사전에 발견할 수 있습니다.

-- 상세 에러 로깅 예시
EXCEPTION
  WHEN OTHERS THEN
    DBMS_OUTPUT.PUT_LINE(
      UTL_HTTP.GET_DETAILED_SQLERRM
    );