오류 해결

컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

Gmail API는 두 가지 수준의 오류 정보를 반환합니다.

  • 헤더의 HTTP 오류 코드 및 메시지
  • 응답 본문에서 오류 처리 방법을 결정하는 데 도움이 되는 추가 세부정보가 포함된 JSON 객체입니다.

Gmail 앱은 REST API를 사용할 때 발생할 수 있는 모든 오류를 포착하고 처리해야 합니다. 이 가이드에서는 특정 API 오류를 해결하는 방법을 설명합니다.

400 오류 해결: 잘못된 요청

이 오류는 코드에서 다음과 같은 오류로 인해 발생할 수 있습니다.

  • 필수 필드 또는 매개변수가 제공되지 않았습니다.
  • 제공된 값 또는 제공된 필드의 조합이 잘못되었습니다.
  • 첨부파일이 잘못되었습니다.

다음은 이 오류의 샘플 JSON 표현입니다.

{
  "error": {
    "code": 400,
    "errors": [
      {
        "domain": "global",
        "location": "orderBy",
        "locationType": "parameter",
        "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order.",
        "reason": "badRequest"
      }
    ],
    "message": "Sorting is not supported for queries with fullText terms. Results are always in descending relevance order."
  }
}

이 오류를 수정하려면 message 필드를 확인하고 그에 따라 코드를 조정하세요.

401 오류 해결: 잘못된 사용자 인증 정보

401 오류는 사용 중인 액세스 토큰이 만료되었거나 유효하지 않음을 나타냅니다. 이 오류는 요청된 범위에 대한 승인 누락으로 인해 발생할 수도 있습니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "authError",
        "message": "Invalid Credentials",
        "locationType": "header",
        "location": "Authorization",
      }
    ],
    "code": 401,
    "message": "Invalid Credentials"
  }
}

이 오류를 해결하려면 장기 갱신 토큰을 사용하여 액세스 토큰을 새로고침하세요. 클라이언트 라이브러리를 사용하는 경우 토큰 갱신이 자동으로 처리됩니다. 이 방법이 실패하면 Gmail로 앱 승인에 설명된 대로 OAuth 흐름을 통해 사용자를 안내하세요.

Gmail 한도에 대한 자세한 내용은 사용량 한도를 참고하세요.

403 오류 해결: 사용량 한도 초과

오류 403은 사용량 한도를 초과했거나 사용자에게 올바른 권한이 없는 경우에 발생합니다. 구체적인 오류 유형을 확인하려면 반환된 JSON의 reason 필드를 평가합니다. 이 오류는 다음과 같은 경우에 발생합니다.

  • 일일 한도를 초과했습니다.
  • 사용자 비율 제한을 초과했습니다.
  • 프로젝트 비율 제한을 초과했습니다.
  • 인증된 사용자의 도메인 내에서 앱을 사용할 수 없습니다.

Gmail 한도에 대한 자세한 내용은 사용량 한도를 참고하세요.

403 오류 해결: 일일 한도 초과

dailyLimitExceeded 오류는 프로젝트의 서비스 API 한도에 도달했음을 나타냅니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "usageLimits",
        "reason": "dailyLimitExceeded",
        "message": "Daily Limit Exceeded"
      }
    ],
    "code": 403,
    "message": "Daily Limit Exceeded"
  }
}

이 오류를 수정하는 방법은 다음과 같습니다.

  1. Google API 콘솔로 이동합니다.
  2. 프로젝트를 선택합니다.
  3. 할당량 탭을 클릭합니다.
  4. 추가 할당량을 요청합니다. 자세한 내용은 추가 할당량 요청을 참조하세요.

Gmail 한도에 대한 자세한 내용은 사용량 한도를 참고하세요.

403 오류 해결: 사용자 비율 한도 초과

userRateLimitExceeded 오류는 사용자별 한도에 도달했음을 나타냅니다. 다음은 이 오류의 JSON 표현입니다.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "reason": "userRateLimitExceeded",
    "message": "User Rate Limit Exceeded"
   }
  ],
  "code": 403,
  "message": "User Rate Limit Exceeded"
 }
}

이 오류를 해결하려면 요청 수를 줄이거나 재시도하도록 애플리케이션 코드를 최적화해 보세요. 요청 재시도에 대한 자세한 내용은 실패한 요청을 재시도하여 오류 해결을 참조하세요.

Gmail 한도에 대한 자세한 내용은 사용량 한도를 참고하세요.

403 오류 해결: 비율 한도 초과

rateLimitExceeded 오류는 사용자가 Gmail API의 최대 요청 비율에 도달했음을 나타냅니다. 이 한도는 요청 유형에 따라 다릅니다. 다음은 이 오류의 JSON 표현입니다.

{
 "error": {
  "errors": [
   {
    "domain": "usageLimits",
    "message": "Rate Limit Exceeded",
    "reason": "rateLimitExceeded",
   }
  ],
  "code": 403,
  "message": "Rate Limit Exceeded"
 }
}

이 오류를 해결하려면 실패한 요청을 다시 시도하세요.

Gmail 한도에 대한 자세한 내용은 사용량 한도를 참고하세요.

403 오류 해결: ID가 {appId}인 앱은 인증된 사용자의 도메인 내에서 사용할 수 없습니다.

domainPolicy 오류는 사용자 도메인의 정책이 앱에서 Gmail에 대한 액세스를 허용하지 않을 때 발생합니다. 다음은 이 오류의 JSON 표현입니다.

{
  "error": {
    "errors": [
      {
        "domain": "global",
        "reason": "domainPolicy",
        "message": "The domain administrators have disabled Gmail apps."
      }
    ],
    "code": 403,
    "message": "The domain administrators have disabled Gmail apps."
  }
}

이 오류를 수정하는 방법은 다음과 같습니다.

  1. 사용자에게 도메인에서 Gmail에 액세스하는 것을 허용하지 않는다고 알립니다.
  2. 도메인 관리자에게 문의하여 앱 액세스를 요청하라고 안내합니다.

429 오류 해결: 요청이 너무 많음

429 '요청이 너무 많음' 오류는 일일 사용자 한도(메일 전송 한도 포함), 대역폭 한도, 사용자별 동시 요청 한도로 인해 발생할 수 있습니다. 각 한도에 대한 정보는 다음과 같습니다. 하지만 각 요청은 실패한 요청을 재시도하거나 여러 Gmail 계정에 처리를 분할하는 방식으로 해결할 수 있습니다. 어떠한 이유로든 사용자별 한도는 늘릴 수 없습니다. 한도에 대한 자세한 내용은 사용량 한도를 참고하세요.

메일 전송 한도

Gmail API는 표준 일일 메일 전송 한도를 적용합니다. 이러한 제한사항은 유료 사용자와 Google Workspace gmail.com 체험판 사용자의 경우에 따라 다릅니다. 이러한 한도는 Google Workspace의 Gmail 전송 한도를 참고하세요.

이 한도는 사용자별로 적용되며 API 클라이언트, 네이티브/웹 클라이언트, SMTP MSA 등 모든 사용자의 클라이언트에서 공유됩니다. 이 한도를 초과하면 다시 시도할 시간이 있는 HTTP 429 Too Many Requests '사용자 비율 제한 초과됨' '(메일 전송)' 오류가 반환됩니다. 일일 한도를 초과하면 요청이 수락되기 전에 여러 시간 동안 이러한 유형의 오류가 발생할 수 있습니다.

메일 전송 파이프라인은 복잡합니다. 사용자가 할당량을 초과하면 API가 429 오류 응답을 반환하기 전에 몇 분 정도 지연될 수 있습니다. 따라서 응답이 200이면 이메일이 성공적으로 전송되었다고 가정할 수 없습니다.

대역폭 한도

API에는 IMAP과 같지만 독립적인, 사용자별 업로드 및 다운로드 대역폭 한도가 있습니다. 이러한 한도는 특정 사용자의 모든 Gmail API 클라이언트에서 공유됩니다.

이러한 한도는 일반적으로 예외적이거나 악의적인 경우에만 발생합니다. 이러한 한도를 초과하면 HTTP 429 Too Many Requests '사용자 비율 제한을 초과했습니다' 오류가 반환되고 재시도할 시간이 제공됩니다. 일일 한도를 초과하면 요청이 수락되기 전에 여러 시간 동안 이러한 유형의 오류가 발생할 수 있습니다.

동시 요청

Gmail API는 사용자별 요율 한도 외에도 사용자별 동시 요청 한도를 적용합니다. 이 한도는 지정된 사용자에 액세스하는 모든 Gmail API 클라이언트에서 공유하며, API 클라이언트가 Gmail 사용자 편지함 또는 백엔드 서버에 과부하를 일으키지 않도록 합니다.

단일 사용자에게 다수의 병렬 요청을 하거나 다수의 요청이 포함된 배치를 전송하는 경우 이 오류가 트리거될 수 있습니다. Gmail 사용자 편지함에 동시에 액세스하는 다수의 독립 API 클라이언트에서도 이 오류가 발생할 수 있습니다. 이 한도를 초과하면 HTTP 429 Too Many Requests '사용자에 대한 동시 요청이 너무 많음' 오류가 반환됩니다.

500 오류 해결: 백엔드 오류

backendError는 요청을 처리하는 동안 예기치 않은 오류가 발생할 때 발생합니다.

{
 "error": {
  "errors": [
   {
    "domain": "global",
    "reason": "backendError",
    "message": "Backend Error",
   }
  ],
  "code": 500,
  "message": "Backend Error"
 }
}

이 오류를 해결하려면 실패한 요청을 다시 시도하세요. 다음은 500 오류 목록입니다.

  • 502 잘못된 게이트웨이
  • 503 서비스를 사용할 수 없음
  • 504 게이트웨이 시간 초과

실패한 요청을 재시도하여 오류 해결하기

증가하는 시간 동안 주기적으로 실패한 요청을 재시도하여 비율 제한, 네트워크 볼륨 또는 응답 시간과 관련된 오류를 처리할 수 있습니다. 예를 들어 1초 후에, 2초 후에, 4초 후에 실패한 요청을 재시도할 수 있습니다. 이 방법을 지수 백오프라고 하며 대역폭 사용량을 개선하고 동시 환경에서 요청 처리량을 극대화하는 데 사용됩니다.

오류 발생 후 최소 1초 후에 재시도를 시작합니다.

사용량 한도 확인 또는 변경, 할당량 상향 조정

프로젝트의 사용량 한도를 확인 또는 변경하거나 할당량 증가를 요청하려면 다음 단계를 따르세요.

  1. 프로젝트의 결제 계정이 아직 없는 경우 계정을 만듭니다.
  2. API 콘솔에서 API 라이브러리의 사용 설정된 API 페이지를 방문하여 목록에서 API를 선택합니다.
  3. 할당량 관련 설정을 확인하고 변경하려면 할당량을 선택합니다. 사용 통계를 확인하려면 사용량을 선택합니다.

일괄 요청

그러나 일괄 처리를 사용하는 것이 좋습니다. 그러나 배치 크기가 클수록 비율 제한이 트리거될 수 있습니다. 요청이 50개를 초과하는 배치는 전송하지 않는 것이 좋습니다. 요청을 일괄 처리하는 방법에 대한 자세한 내용은 요청 일괄 처리를 참조하세요.