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