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"
}
}
이 오류를 수정하는 방법은 다음과 같습니다.
- Google API 콘솔 방문
- 프로젝트를 선택합니다.
- 할당량 탭을 클릭합니다.
- 추가 할당량을 요청합니다. 자세한 내용은 추가 할당량 요청을 참조하세요.
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}인 앱을 인증된 사용자의 도메인 내에서 사용할 수 없음
사용자 도메인의 정책에서 앱의 Gmail 액세스를 허용하지 않으면 domainPolicy 오류가 발생합니다. 다음은 이 오류를 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."
}
}
이 오류를 수정하는 방법은 다음과 같습니다.
- 도메인에서 앱의 Gmail 액세스를 허용하지 않는다고 사용자에게 알립니다.
- 도메인 관리자에게 문의하여 앱 액세스를 요청하도록 사용자에게 안내합니다.
429 오류 해결: 요청이 너무 많음
429 '요청이 너무 많음' 오류는 일일 사용자당 한도(메일 전송 한도 포함), 대역폭 한도 또는 사용자당 동시 요청 한도로 인해 발생할 수 있습니다. 각 한도에 대한 정보는 다음과 같습니다. 하지만 각 한도는 실패한 요청을 다시 시도하거나 여러 Gmail 계정으로 처리를 분할하면 해결할 수 있습니다. 사용자당 한도는 어떤 이유로든 늘릴 수 없습니다. 한도에 대한 자세한 내용은 사용량 한도를 참고하세요.
메일 전송 한도
Gmail API는 일일 표준 메일 전송 한도를 적용합니다. 이 한도는 유료 사용자와 Google Workspace 무료 체험판 사용자 간에는 다릅니다. 이러한 한도는 Google Workspace의 Gmail 전송 한도를 참고하세요.
이러한 한도는 사용자별로 적용되며 API 클라이언트, 기본/웹 클라이언트 또는 SMTP MSA 등 사용자의 모든 클라이언트가 공유합니다. 이러한 한도를 초과하면 HTTP 429 Too Many Requests 'User-rate limit exceeded'(메일 전송) 오류가 반환되고 재시도 시간이 반환됩니다.
일일 한도를 초과하면 요청이 수락되기 전까지 몇 시간 동안 이러한 유형의 오류가 발생할 수 있습니다.
메일 전송 파이프라인은 복잡합니다. 사용자가 할당량을 초과하면 API가 429 오류 응답을 반환하기까지 몇 분 정도 지연될 수 있습니다. 따라서 응답 200은 이메일이 성공적으로 전송되었음을 의미할 수 없습니다.
대역폭 한도
API에는 IMAP과 같지만 IMAP과 별개인 사용자별 업로드 및 다운로드 대역폭 한도가 있습니다. 이러한 한도는 특정 사용자의 모든 Gmail API 클라이언트에서 공유됩니다.
일반적으로 이러한 한도는 예외적이거나 악의적인 상황에서만 발생합니다.
이 제한을 초과하면 HTTP 429 Too Many Requests '사용자 비율 제한 초과' 오류가 반환되고 재시도 시간이 반환됩니다.
일일 한도를 초과하면 요청이 수락되기 전까지 몇 시간 동안 이러한 유형의 오류가 발생할 수 있습니다.
동시 요청
Gmail API는 사용자당 rate 제한 외에 사용자별 동시 요청 제한을 적용합니다. 이 한도는 특정 사용자에 액세스하는 모든 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초 후에 재시도 기간이 시작됩니다.
사용량 한도 확인 또는 변경, 할당량 늘리기
프로젝트의 사용량 한도를 확인 또는 변경하거나 할당량 증가를 요청하려면 다음 단계를 따르세요.
- 프로젝트의 결제 계정이 아직 없는 경우 계정을 만듭니다.
- API 콘솔에서 API 라이브러리의 사용 설정된 API 페이지를 방문하여 목록에서 API를 선택합니다.
- 할당량 관련 설정을 확인하고 변경하려면 할당량을 선택합니다. 사용 통계를 확인하려면 사용량을 선택합니다.
일괄 요청
일괄 처리를 사용하는 것이 좋지만 배치 크기가 클수록 비율 제한이 트리거될 수 있습니다. 요청 수가 50개를 초과하는 배치는 전송하지 않는 것이 좋습니다. 요청을 일괄 처리하는 방법에 대한 자세한 내용은 요청 일괄 처리를 참조하세요.