Loading

Marketing Cloud 가 제공하는 API 이용에 관한 고려사항 및 FAQ

게시 일자: Apr 17, 2026
상세 설명
Marketing Cloud Engagement의 Web API 이용 시 실패 없는 연동을 위한 유의사항을 해설합니다. 일시적인 오류에 대비한 자동 재시도(Retry) 구현의 중요성, 각종 타임아웃 설정, 로그 수집 등 API를 안정적으로 가동하기 위한 방법에 대해 기재합니다.
솔루션
본 문서에서는 Marketing Cloud가 제공하는 Web API 이용을 검토할 때 유의해야 할 주제와 자주 묻는 질문을 소개합니다.
 
*HTTP 상태 코드(Status Code)가 500번대로 응답되는 것을 이후 500 오류 라고 표기합니다.
 
<검토 포인트>
Point 1 : 자동 재시도(Retry)를 구현할 것 (중요)
 
API 요청 시 일시적인 오류(주로 500 오류)가 응답될 수 있습니다. 그 요인은 API 서비스의 부하 요인이나 인터넷 환경 등 다양하지만, 실제 이용 과정에서 일시적인 오류 발생은 피할 수 없습니다. 따라서 일시적인 오류 발생을 미리 상정하고, 재시도 메커니즘을 반드시 검토해야 합니다.
구체적으로는 API 요청을 발행하는 애플리케이션에서 예상 가능한 에러 핸들링 처리를 추가합니다. 그리고 오류가 발생했을 때 적절한 횟수와 타이밍에 API 요청을 자동으로 다시 시도하는 로직을 구현합니다.
이러한 일시적 오류는 당사 서비스 측 이외의 요인으로 발생하는 경우도 많기 때문에, 당사 측의 대응만으로는 완벽히 줄일 수 없습니다. 따라서 자동 재시도 구현이 매우 중요하며, 이를 통해 API 서비스를 더욱 안정적으로 이용할 수 있습니다.
 
Point 2 : API 클라이언트의 타임아웃 시간 조정을 검토할 것 (중계 장비 포함)
Point 1과 마찬가지로, 여러 요인에 의해 API 요청 응답이 지연될 수 있습니다. 이때 API 클라이언트 측의 타임아웃 시간이 너무 짧으면, 당사 API 서비스의 응답을 기다리지 못하고 애플리케이션이 처리를 종료해 버릴 수 있습니다. 이는 불필요한 오류 빈도를 높이는 원인이 되므로, 타임아웃이 빈번하게 확인되는 경우 클라이언트 측의 타임아웃 시간 조정을 검토하십시오.
 
여기서 말하는 API 클라이언트란 API 요청을 발행하는 애플리케이션이나 서버 외에도, 경로상에 있는 API 중계 서버나 네트워크 장비를 포함합니다. 애플리케이션의 타임아웃만 연장하더라도 중계 장비의 타임아웃이 더 짧으면 해당 장비에서 타임아웃을 응답하게 되어 오류 빈도가 줄어들지 않습니다. 따라서 어떤 장비에서 타임아웃이 발생하는지 확인하여 연장하는 것이 중요합니다.
반대로, 당사 API 타임아웃이 너무 길어 문제가 되는 경우에는 클라이언트 측 장비의 타임아웃을 의도적으로 짧게 설정하는 방법도 고려할 수 있습니다.
※ 타임아웃 권장 값에 대한 문의가 많으나, 고정된 권장 값은 없으므로 이용 중인 애플리케이션의 요건에 맞춰 검토해 주십시오. 당사 API 서비스의 타임아웃 기준을 참고하시려면 API Limits and Guidelines를 참조하시기 바랍니다.
 
Point 3 : 상세 로그를 남길 것
API 요청 오류 원인 조사 의뢰를 받는 경우, 정밀한 조사를 위해서는 API 요청/응답 데이터가 반드시 필요합니다. 따라서 API를 이용할 때는 요청/응답의 헤더와 바디를 포함한 상세 로그를 남겨야 합니다.
 
HTTP 상태 코드 400번대(Bad Request)가 발생하면 요청 내용에 문제가 있음을 의미합니다. 해당 요청의 응답 바디(Body) 내에 문제가 있는 부분이 표시되므로, 이를 먼저 확인하여 요청 값에 오류가 없는지 정밀하게 점검하십시오. 대표적인 에러 상세 내용은 아래 참고 정보의 문서를 확인해 주십시오. 만약 요청에 문제가 없음에도 해결되지 않아 서포트 케이스를 생성하실 경우, 요청과 응답의 전체 데이터를 제공해 주시기 바랍니다.
 
※ 이때, 클라이언트 자체 앱 로그나 가공된 정보(일부 생략된 정보)만 제공해 주시는 경우가 있습니다. Salesforce Marketing Cloud가 응답하는 모든 정보가 포함되지 않으면 조사가 불가능할 수 있으므로, 로그는 HTTP 요청/응답을 가급적 생략 없이 남겨야 합니다.
 
참고 정보:
 
Point 4 : 토큰 취득은 가능한 최소화할 것
하나의 처리를 실행할 때마다 토큰 취득(POST /v2/token)을 수행하면 요청 수가 단순 계산으로 2배가 됩니다. 요청 수가 많아지면 일시적인 오류나 요청 제한(Rate Limit)에 걸리기 쉬워집니다. 토큰은 20분의 유효기간이 있으므로, 유효기간 내라면 취득한 토큰을 최대한 재사용하는 방식을 권장합니다.
 
Point 5 : 엔드 유저용 웹 페이지·모바일 앱에서 직접 API를 호출하는 것은 가급적 지양할 것
사용자가 사용하는 기기(웹/모바일)에서 직접 API 요청을 실행하도록 구현하면 다음과 같은 우려 사항이 있습니다.
・보안 측면: 사용자 단말기에 API 실행 권한이 있는 기밀 정보가 유지되므로 관리가 매우 중요해집니다.
・안정성 측면: 당사 API 서비스 변경 시 웹/모바일 앱의 업데이트가 필요할 수 있습니다.
・사용자 경험: 점검이나 인시던트로 API 오류가 발생할 경우, 화면 로딩 지연, 부적절한 표시, 데이터 불일치 등이 발생하여 사용자 이용에 방해가 될 수 있습니다.
 
따라서 앱에서 직접 요청하는 대신 자체 API 서버를 거쳐서 대리로 실행하는 패턴을 권장합니다. 이 경우 경로가 늘어나 응답 속도는 느려질 수 있으므로, 프론트엔드나 서버 측에서 사용자 경험을 해치지 않도록 설계해야 합니다.
 
<문의 시 제공 권장 정보>
API 요청 오류 조사를 의뢰하실 경우 다음 정보를 함께 제출해 주십시오. 오류가 여러 건 발생했다면, 동일한 유형의 대표 사례 2~3건 정도를 샘플링하여 제공해 주셔도 무방합니다.
・요청 일시
・요청 URL, 메서드 (Method)
・요청 바디 (Request Body)
・응답 바디 (Response Body)
 
또한, 500 오류가 연속적으로 대량 발생하여 요청 내용과 무관해 보일 경우 아래 정보로 대체 가능합니다.
・오류가 확인된 시간대
・오류 발생 빈도 (예: 3분간 10건의 요청 중 8건 발생 등)
・기타 오류 상세 정보 (응답 바디, 클라이언트 앱 로그 등)
 
※ 서포트 케이스는 원칙적으로 1개 케이스당 1개 질문이 원칙이므로, 오류 종류가 다를 경우 케이스 분할을 요청드릴 수 있습니다.
 
<문의 시 자주 발생하는 상황: 에러 수의 차이>
API 클라이언트에서 기록된 에러 횟수와 당사 API 서비스 상에서 확인되는 에러 횟수에 차이가 있을 수 있습니다.
예:
API 클라이언트에서 확인된 500 에러 수 = 10회
당사 시스템에 기록된 500 에러 수 = 0회
 
이런 경우, Point 2에서 언급한 것처럼 경로상에 있는 중계 장비나 애플리케이션에서 직접 오류가 발생했을 가능성이 큽니다.
따라서 해당 오류를 발생시키는 장비(중계 서버 등)에서 상세 내용을 확인해야 합니다.
 
<FAQ>
Q) 500 오류가 응답되는 원인은 무엇인가요?
A) 원인은 다양하지만 발생 빈도에 따라 상황이 다릅니다.
・단시간에 연속 대량 발생: 당사 서비스 장애 가능성이 있습니다. 먼저 [Trust 사이트]에서 가동 현황을 확인하십시오.
・최근 들어 에러 빈도가 명확히 상승: 당사 측의 조치가 필요한 상황일 수 있습니다. <문의 시 제공 권장 정보>와 함께 최근 빈도 추이 등 경향성을 제공해 주십시오.
・빈도가 낮고 산발적 발생: 대부분 일시적인 재현 불가 오류, 점검, 인터넷 경로 불안정, 고객사-당사 서버 사이 중계 장비의 타임아웃 등 당사 로그에 남지 않는 외부 요인인 경우가 많습니다. 이러한 오류는 0으로 만드는 것이 불가능하므로 발생을 전제로 설계해야 합니다. 따라서 개별 오류 조사보다는 재시도(Retry) 구현이 가장 효과적인 대책입니다. 
이는 API뿐만 아니라 SFTP 등 웹을 경유하는 모든 통신에 공통되는 사항입니다. ( FTP에 관한 내용 )
 
Q) 재시도(Retry) 방식에 권장 사항이 있나요?
A) 케이스 바이 케이스이므로 당사의 공식 권장 방식은 없습니다. 일반적인 방식으로는 일정 간격으로 여러 번 실행 (예: 15초 간격으로 3회) 하거나, 간격을 점진적으로 늘리는 방식 (예: 3초 후, 10초 후, 60초 후...) 등이 있습니다.
 
Q) 요청 수 제한이나 타임아웃 등 제한 사항을 확인하고 싶습니다.
A) 아래 참고 1 문서를 확인하십시오. 부하가 큰 요청을 단시간에 집중시키면 일시적 제한이 걸릴 수 있습니다. 참고 2와 같이 서비스 성능에 악영향을 줄 정도의 요청이 들어오면 상태 코드 429와 함께 제한됩니다. 특히 Point 4처럼 토큰을 매번 새로 취득하면 이 제한에 걸리기 쉬우므로 주의하십시오.
 
 
Q) API 클라이언트 이용 방법(도구 사용법, 명령어 등)이나 특정 언어(Python, Curl 등)용 샘플 코드를 받을 수 있나요?
A) 이는 당사 제품의 범위를 벗어나는 영역이므로 서포트 케이스를 통해 공식 답변을 드리지 않습니다.
만약 제품 자체의 문제로 의심된다면 상세한 테스트 결과와 함께 문의해 주시기 바랍니다.
Knowledge 기사 번호

001035940

 
로드 중
Salesforce Help | Article