클라우드 API

WhatsApp Business 플랫폼 > 클라우드 API

클라우드 API 오류 코드

클라우드 API는 그래프 API를 기반으로 합니다. 그래프 API 오류 응답을 처리하는 데 익숙하지 않을 경우 그래프 API 오류 처리 문서를 참조하세요.

일반적으로 code 값과 details 페이로드 속성을 중심으로 앱 오류 처리 로직을 빌드하는 것이 좋습니다. 이러한 속성과 값은 기본 오류를 더욱 잘 보여줍니다.

API 오류 응답 페이로드에 전용 속성이 없는 코드 제목은 message 값에 포함됩니다. 그러나 제목은 최종적으로 사용 중단될 예정이므로 오류 처리 로직에서 제목을 사용하지 않는 것이 좋습니다.

오류 수신: 동기식 및 비동기식

클라우드 API 오류는 그래프 API 응답으로써 동기식으로 반환되거나 Webhooks를 통해 비동기식으로 반환됩니다. 때로는 두 가지 방법을 통해 반환되기도 합니다.

클라우드 API에서 오류를 처리할 때 그래프 API 응답과 messages Webhooks를 모두 모니터링하는 것이 좋습니다. messages Webhooks 필드를 구독하는 경우, 지원되는 비동기식 유형의 오류가 발생하면 오류 알림을 받게 됩니다.

오류 응답 Webhooks 및 구문

클라우드 API 오류는 다음의 Webhooks 개체에 표시할 수 있습니다.

클라우드 API

  • entry.changes.value.errors
  • entry.changes.value.messages.errors

온프레미스 API

  • errors

오류 응답 구문

{
  "error": {
    "message": "<MESSAGE>",
    "type": "<TYPE>",
    "code": <CODE>,
    "error_data": {
        "messaging_product": "whatsapp",
        "details": "<DETAILS>"
    },
    "error_subcode": <ERROR_SUBCODE>
    "fbtrace_id": "<FBTRACE_ID>"
  }
}

오류 응답 내용

속성 값 유형 설명

code

정수

오류 코드입니다. 하위 코드 또는 HTTP 응답 상태 코드 대신 오류 코드를 중심으로 앱의 오류 처리를 빌드하는 것이 좋습니다.

details

문자열

오류 설명과 오류의 원인일 가능성이 가장 높은 이유에 대한 설명입니다. 유효하지 않은 매개변수나 허용 가능한 값 등, 오류를 해결하는 방법에 대한 정보도 포함할 수 있습니다.

error_subcode

정수

사용 중단되었습니다. v16.0 이상 응답에서 반환되지 않습니다.


그래프 API 하위 코드. 모든 응답에 하위 코드가 포함되는 것은 아니므로 대신 code 및 details 속성을 중심으로 오류 처리 로직을 빌드하는 것이 좋습니다.

fbtrace_id

문자열

기술 지원에 문의할 때 포함할 수 있는 추적 ID입니다. 이 ID는 오류를 디버그하는 데 도움이 될 수 있습니다.

message

문자열

오류 코드와 제목의 조합입니다. 예: (#130429) Rate limit hit.

messaging_product

문자열

메시지 제품입니다. 이는 언제나 클라우드 API 응답에 대한 whatsapp 문자열이 됩니다.

type

문자열

오류 유형입니다.

응답 샘플

{
  "error": {
    "message": "(#130429) Rate limit hit",
    "type": "OAuthException",
    "code": 130429,
    "error_data": {
        "messaging_product": "whatsapp", 
        "details": "Message failed to send because there were too many messages sent from this phone number in a short period of time"
    },
    "error_subcode": 2494055,
    "fbtrace_id": "Az8or2yhqkZfEZ-_4Qn_Bam"
  }
}

오류 코드

승인 오류

코드 설명 가능한 해결 방법 HTTP 상태 코드

0

AuthException

앱 사용자를 인증할 수 없습니다.

일반적으로, 이는 포함된 액세스 토큰이 만료되었거나 무효화되었거나 앱 사용자가 모든 앱이 데이터에 액세스하지 못하도록 설정을 변경했음을 의미합니다. 새로운 액세스 토큰을 얻는 것이 좋습니다.

401

권한 없음

3

API 메서드

기능 또는 권한 문제입니다.

액세스 토큰 디버거를 사용하여 엔드포인트에서 요구하는 권한을 앱에 부여했는지 확인합니다. 문제 해결을 참조하세요.

500

내부 서버 오류

10

권한이 거부됨

권한이 부여되지 않았거나 삭제되었습니다.

액세스 토큰 디버거를 사용하여 엔드포인트에서 요구하는 권한을 앱에 부여했는지 확인합니다. 문제 해결을 참조하세요.

비즈니스 공개 키를 설정하는 데 사용한 전화번호가 허용 리스트에 추가되어 있는지 확인하세요.

403

금지됨

190

액세스 토큰이 만료됨

액세스 토큰이 만료되었습니다.

새 액세스 토큰을 받으세요.

401

권한 없음

200-299

API 권한

권한이 부여되지 않았거나 삭제되었습니다.

액세스 토큰 디버거를 사용하여 엔드포인트에서 요구하는 권한을 앱에 부여했는지 확인합니다. 문제 해결을 참조하세요.

403

금지됨

제한 오류

코드 설명 가능한 해결 방법 HTTP 상태 코드

4

API 호출이 너무 많음

앱이 API 호출 사용 제한에 도달했습니다.

앱 대시보드에서 앱을 읽어들여 앱 사용 제한 섹션을 보고 앱이 사용 제한에 도달했는지 확인하세요. 사용 제한에 도달한 경우, 나중에 다시 시도하거나 앱이 보내는 API 쿼리의 빈도나 횟수를 낮추세요.

400

잘못된 요청

80007

사용 제한 이슈

WhatsApp Business 계정이 사용 제한에 도달했습니다.

WhatsApp Business 계정 사용 제한을 참조하세요. 나중에 다시 시도하거나 앱이 보내는 API 쿼리의 빈도나 횟수를 줄이세요.

400

잘못된 요청

130429

사용 제한 도달

클라우드 API 메시지 처리량 한도에 도달했습니다.

앱이 API의 처리량 제한에 도달했습니다. 처리량을 참조하세요. 나중에 다시 시도하거나 앱이 메시지를 보내는 빈도를 줄이세요.

400

잘못된 요청

131048

스팸 사용 제한 도달

이 전화번호에서 전송 가능한 메시지 수에 제한이 있으므로 메시지 전송이 실패했습니다. 이전에 메시지가 너무 많이 차단되었거나 스팸으로 플래그되었기 때문일 수 있습니다.

WhatsApp 관리자에서 품질 상태를 확인하고 자세한 내용은 품질 기반 사용 제한 문서를 참조하세요.

400

잘못된 요청

131056

(비즈니스 계정, 소비자 계정) 페어링 사용 제한 도달

짧은 시간에 보내는 사람 전화번호에서 동일한 받는 사람 전화번호로 너무 많은 메시지가 전송되었습니다.

메시지를 동일한 전화번호로 전송하고자 할 경우 기다렸다가 이 작업을 다시 시도하세요. 기다리지 않고 다른 전화번호로 메시지를 보낼 수도 있습니다.

400

잘못된 요청

133016

계정 등록/등록 취소 사용 제한 초과

단시간에 이 전화번호에 대한 등록 또는 등록 취소 시도가 너무 많이 발생하여 등록 또는 등록 취소가 실패했습니다.

비즈니스 전화번호가 등록/등록 해제 시도 제한에 도달하여 차단되었습니다. 전화번호의 차단이 해제되면 다시 시도하세요. 등록 문서의 '제한'을 참조하세요.

400

잘못된 요청

무결성 오류

코드 설명 가능한 해결 방법 HTTP 상태 코드

368

정책 위반으로 일시적으로 차단됨

앱에 연결된 WhatsApp Business 계정이 플랫폼 정책 위반으로 인해 제한되거나 비활성화되었습니다.

정책 위반과 해결 방법에 대해 알아보려면 정책 규정 시행 문서를 참조하세요.

403

금지됨

130497

비즈니스 계정은 이 국가의 사용자에게 메시지를 보내는 기능이 제한됩니다.

WhatsApp Business 계정은 특정 국가의 사용자에게 메시지를 보내는 기능이 제한됩니다.

비즈니스 카테고리에서 메시지 전송이 허용된 국가에 대한 자세한 내용은 WhatsApp Business 메시지 정책을 참조하세요.

403

금지됨

131031

계정이 잠김

앱과 연결된 WhatsApp Business 계정이 플랫폼 정책 위반으로 인해 제한되었거나 비활성화되었거나, WhatsApp Business 계정의 데이터 세트와 비교하여 요청에 포함된 데이터를 확인할 수 없습니다(예: 요청에 포함된 2단계 PIN이 잘못됨).

정책 위반과 해결 방법에 대해 알아보려면 정책 규정 시행 문서를 참조하세요.


또한 상태 API를 사용할 수 있으며, 이는 계정이 잠긴 이유에 대한 추가 인사이트를 제공할 수 있습니다.

403

금지됨

기타 오류

코드 설명 가능한 해결 방법 HTTP 상태 코드

1

API 알 수 없음

요청이 잘못되었거나 서버 오류일 수 있습니다.

API 상태 정보를 확인하려면 WhatsApp Business 플랫폼 상태 페이지를 참조하세요. 서버가 중단되지 않은 경우 엔드포인트 참고 자료를 참조하고, 요청의 형식이 올바르게 지정되었고 모든 엔드포인트 요구 사항을 준수하는지 확인하세요.

400

잘못된 요청

2

API 서비스

가동 중지 시간이나 과부하로 인한 일시적 현상입니다.

다시 시도하기 전에 API 상태 정보를 확인하려면 WhatsApp Business 플랫폼 상태 페이지를 참조하세요.

503

서비스 이용 불가

33

매개변수 값이 유효하지 않음

비즈니스 전화번호가 삭제되었습니다.

비즈니스 전화번호가 정확한지 확인하세요.

400

잘못된 요청

100

잘못된 매개변수

요청에 하나 이상의 지원되지 않거나 철자가 잘못된 매개변수가 포함되었습니다.

지원되는 매개변수의 종류와 철자를 확인하려면 엔드포인트 참고 자료를 참조하세요.

비즈니스 공개 키를 설정할 때 PEM 형식의 유효한 2,048비트 RSA 공개 키여야 합니다.

등록하는 전화번호 ID와 이전에 저장한 전화번호 ID가 일치해야 합니다.

매개변수에 유형에 대한 길이 제한이 적용되는지 확인하세요.

400

잘못된 요청

130472

사용자 번호가 실험에 포함됨

메시지가 실험에서 전송되지 않았습니다.

마케팅 메시지 실험을 참조하세요.

400

잘못된 요청

131000

오류 발생

알 수 없는 오류로 인해 메시지를 보내지 못했습니다.

비즈니스 공개 키를 설정할 때 서명을 계산하지 못했거나, GraphQL 엔드포인트를 호출하지 못했거나, GraphQL 엔드포인트가 오류를 반환했습니다.

다시 시도하세요. 오류가 지속되면 기술 지원 티켓을 개설하세요.

500

내부 서버 오류

131005

액세스가 거부됨

권한이 부여되지 않았거나 삭제되었습니다.

액세스 토큰 디버거를 사용하여 엔드포인트에서 요구하는 권한을 앱에 부여했는지 확인합니다. 문제 해결을 참조하세요.

403

금지됨

131008

필수 매개변수가 누락됨

요청에 필수 매개변수가 누락되었습니다.

어떤 매개변수가 필요한지 확인하려면 엔드포인트의 참고 자료를 참조하세요.

400

잘못된 요청

131009

매개변수 값이 유효하지 않음

하나 이상의 매개변수 값이 잘못되었습니다.

각 매개변수에 어떤 값이 지원되는지 확인하려면 엔드포인트의 참고 자료를 참조하세요. 전화번호를 WhatsApp Business 계정에 추가하는 방법을 확인하려면 전화번호를 참조하세요.

400

잘못된 요청

131016

서비스 이용 불가

서비스를 일시적으로 사용할 수 없습니다.

다시 시도하기 전에 API 상태 정보를 확인하려면 WhatsApp Business 플랫폼 상태 페이지를 참조하세요.

500

내부 서버 오류

131021

받는 사람과 보내는 사람이 동일할 수 없음

보내는 사람과 받는 사람 전화번호가 같습니다.

보내는 사람과 다른 전화번호로 메시지를 보내세요.

400

잘못된 요청

131026

메시지 전달 불가

메시지를 전달할 수 없습니다. 다음과 같은 이유가 있을 수 있습니다.

  • 받는 사람 전화번호가 WhatsApp 전화번호가 아닙니다.
  • 국가 번호가 +91번(인도)인 WhatsApp 사용자에게 인증 템플릿을 보냅니다. 현재 인증 템플릿을 인도의 WhatsApp 사용자에게 보낼 수 없습니다.
  • 받는 사람이 새로운 서비스 약관과 개인정보처리방침에 동의하지 않았습니다.
  • 받는 사람이 오래된 WhatsApp 버전을 사용하고 있습니다. 다음의 WhatsApp 버전 이상을 사용해야 합니다.
    • Android: 2.21.15.15
    • SMBA: 2.21.15.15
    • iOS: 2.21.170.4
    • SMBI: 2.21.170.4
    • KaiOS: 2.2130.10
    • 웹: 2.2132.6

WhatsApp 외의 다른 통신 수단을 사용하는 경우 WhatsApp 사용자에게 다음 작업을 요청하세요.

  • WhatsApp 비즈니스 전화번호로 실제로 메시지를 보낼 수 있는지 확인합니다.
  • 최신 서비스 약관을 수락했는지 확인합니다(아직 서비스 약관을 수락하지 않은 경우 설정 > 도움말 또는 설정 > 앱 정보에서 최신 약관/정책을 수락하라는 메시지가 표시됨).
  • WhatsApp 클라이언트의 최신 버전으로 업데이트합니다.

400

잘못된 요청

131042

비즈니스 자격 요건 결제 이슈

결제 수단과 관련된 오류가 발생했습니다.

WhatsApp Business 계정 청구 정보를 참조하고 청구를 올바르게 설정했는지 확인하세요.

일반적인 문제:

  • 결제 계정이 WhatsApp Business 계정에 연결되지 않음
  • 크레딧 라인이 한도를 초과함
  • 크레딧 라인(결제 계정)이 설정되지 않았거나 활성화되지 않음
  • WhatsApp Business 계정이 삭제됨
  • WhatsApp Business 계정이 정지됨
  • 시간대가 설정되지 않음
  • 통화가 설정되지 않음
  • MessagingFor 요청(OBO)이 대기 중이거나 거절됨
  • 유효한 결제 수단 없이 대화 무료 티어 한도를 초과함

400

잘못된 요청

131045

잘못된 인증서

전화번호 등록 오류로 인해 메시지를 보내지 못했습니다.

다시 시도하기 전에 전화번호를 등록하세요.

500

내부 서버 오류

131047

재참여 메시지

받는 사람이 마지막으로 보낸 사람 전화번호에 답장한 지 24시간 이상이 지났습니다.

대신 메시지 템플릿을 사용하여 비즈니스에서 시작한 메시지를 받는 사람에게 보내세요.

400

잘못된 요청

131049

Meta가 메시지를 전송하지 않았습니다.

이 메시지는 건강한 에코시스템 참여를 유지하기 위해 전송되지 않았습니다.

이 오류 코드를 수신하였고 제한이 원인인 것으로 의심되는 경우 전송을 바로 다시 시도하지 마세요. 대신 메시지가 전달될 때까지 점점 시간 간격을 늘려 가면서 메시지 전송을 다시 시도하세요. 제한이 적용되는 시간이 상이할 수 있기 때문입니다.

자세한 내용은 사용자당 마케팅 템플릿 메시지 제한을 참조하세요.

400

잘못된 요청

131051

지원되지 않는 메시지 유형

지원되지 않는 메시지 유형입니다.

지원되는 메시지 유형으로 다시 시도하기 전에 메시지에서 지원되는 메시지 유형을 확인하세요.

400

잘못된 요청

131052

미디어 다운로드 오류

사용자가 보낸 미디어를 다운로드할 수 없습니다.

WhatsApp 사용자 메시지에 포함된 미디어를 다운로드할 수 없습니다. 자세한 내용은 이 메시지를 수신했을 때 트리거된 메시지 Webhooks의 error.error_data.details 값을 참조하세요.

WhatsApp 사용자에게 WhatsApp 외의 다른 방법을 사용하여 미디어 파일을 보내달라고 요청합니다.

400

잘못된 요청

131053

미디어 업로드 오류

메시지에서 사용한 미디어를 업로드할 수 없습니다.

하나 이상의 이유(예: 지원되지 않는 미디어 유형)로 인해 미디어를 업로드하지 못했습니다.

자세한 내용은 이 메시지를 전송하지 못했을 때 트리거된 메시지 Webhooks의 error.error_data.details 값을 참조하세요.

오류를 일으키는 모든 미디어 파일을 조사하고 실제로 지원되는 파일인지 확인하는 것이 좋습니다. 예를 들어 UNIX에서는 명령줄을 통해 파일 검사를 사용하여 MIME 유형을 확인할 수 있습니다.

file -I rejected-file.mov

지원되는 MIME 유형인지 확인할 수 있습니다. 지원되는 미디어 유형을 참조하세요.

400

잘못된 요청

131057

유지 보수 모드의 계정

비즈니스 계정이 유지 보수 모드입니다.

WhatsApp Business 계정이 유지 보수 모드입니다. 가능한 이유 중 하나는 해당 계정이 처리량 업그레이드를 거치는 중이기 때문일 수 있습니다.

500

잘못된 요청

132000

템플릿 매개변수 개수 불일치

요청에 포함된 가변 매개변수 값의 수가 템플릿에 정의된 가변 매개변수 수와 일치하지 않습니다.

메시지 템플릿 가이드라인을 참조하고 템플릿에 정의된 모든 가변 매개변수 값이 요청에 포함되었는지 확인하세요.

400

잘못된 요청

132001

템플릿이 존재하지 않음

템플릿이 지정된 언어로 존재하지 않거나 템플릿이 승인되지 않았습니다.

템플릿이 승인되었고 템플릿 이름과 언어 로캘이 올바른지 확인하세요. 메시지 템플릿 가이드라인을 따르세요.

404

찾을 수 없음

132005

템플릿 하이드레이션 텍스트가 너무 김

번역된 텍스트가 너무 깁니다.

WhatsApp 관리자에서 템플릿이 번역되었는지 확인하세요. 품질 평가 및 템플릿 상태를 참조하세요.

400

잘못된 요청

132007

템플릿 형식 문자 정책 위반

템플릿 내용이 WhatsApp 정책을 위반합니다.

위반의 원인이 될 만한 이유를 확인하려면 거부 이유를 참조하세요.

400

잘못된 요청

132012

템플릿 매개변수 형식 불일치

가변 매개변수 값의 형식이 잘못되었습니다.

요청에 포함된 가변 매개변수 값이 템플릿에서 지정된 형식을 사용하지 않습니다. 메시지 템플릿 가이드라인을 참조하세요.

400

잘못된 요청

132015

템플릿이 일시 중단됨

템플릿이 낮은 품질로 인해 일시 중단되어서 템플릿 메시지로 전송할 수 없습니다.

템플릿을 수정하여 품질을 개선하고 승인을 받은 후에 다시 시도하세요.

400

잘못된 요청

132016

템플릿이 비활성화됨

템플릿이 낮은 품질로 인해 너무 많이 일시 중단되었고 현재 영구적으로 비활성화되었습니다.

다른 콘텐츠로 새로운 템플릿을 만드세요.

400

잘못된 요청

132068

플로가 차단됨

플로가 차단된 상태입니다.

플로를 수정하세요.

400

잘못된 요청

132069

플로가 제한됨

플로가 제한된 상태이고 지난 1시간 동안 이미 이 플로를 사용하는 메시지 10개가 전송되었습니다.

플로를 수정하세요.

400

잘못된 요청

133000

불완전한 등록 해제

이전의 등록 해제 시도가 실패했습니다.

전화번호의 등록을 다시 해제하고 등록하세요.

500

내부 서버 오류

133004

서버를 일시적으로 사용할 수 없음

서버를 일시적으로 사용할 수 없습니다.

다시 시도하기 전에 WhatsApp Business 플랫폼 상태 페이지에서 API 상태 정보와 응답 details 값을 확인하세요.

503

서비스 이용 불가

133005

2단계 인증 PIN 불일치

2단계 인증 PIN이 잘못되었습니다.

요청에 포함된 2단계 인증 PIN이 올바른지 확인하세요.


2단계 인증 PIN을 재설정하는 방법은 다음과 같습니다.


  1. 2단계 인증을 비활성화합니다.
  2. 새로운 PIN을 포함한 POST 요청을 전화번호 엔드포인트로 보냅니다.

400

잘못된 요청

133006

전화번호 재인증 필요

등록하기 전에 전화번호를 확인해야 합니다.

등록하기 전에 전화번호를 확인하세요.

400

잘못된 요청

133008

2단계 인증 PIN 시도 횟수가 너무 많음

이 전화번호에 대해 2단계 인증 PIN 시도 횟수가 너무 많습니다.

details 응답 값에 지정된 시간이 지난 이후에 다시 시도하세요.

400

잘못된 요청

133009

2단계 인증 PIN 시도가 너무 빠름

2단계 인증 PIN을 너무 빨리 입력했습니다.

다시 시도하기 전에 details 응답 값을 확인하세요.

400

잘못된 요청

133010

전화번호가 등록되지 않음

WhatsApp Business 플랫폼에 전화번호가 등록되지 않았습니다.

다시 시도하기 전에 전화번호를 등록하세요.

400

잘못된 요청

133015

이 전화번호를 등록하기 전에 잠시 기다려 주세요

등록하려는 전화번호가 최근에 삭제되었고 아직 삭제가 완료되지 않았습니다.

5분 후에 요청을 다시 시도하세요.

400

잘못된 요청

135000

일반 사용자 오류

요청 매개변수의 알 수 없는 오류로 인해 메시지 전송이 실패했습니다.

올바른 구문을 사용하여 엔드포인트를 쿼리하는지 확인하려면 엔드포인트 참고 자료를 참조하세요. 응답에 이 오류 코드가 계속 표시되는 경우 고객 지원에 문의하세요.

400

잘못된 요청