Gmail API는 두 가지 수준의 오류 정보를 반환합니다.
- 헤더의 HTTP 오류 코드 및 메시지
- 오류를 처리하는 방법을 결정하는 데 도움이 되는 추가 세부정보가 포함된 응답 본문의 JSON 객체
Gmail 앱은 REST API를 사용할 때 발생할 수 있는 모든 오류를 포착하고 처리해야 합니다. 이 가이드에서는 특정 Gmail API 오류를 해결하는 방법을 안내합니다.
HTTP 상태 코드 요약
| 오류 코드 | 설명 |
|---|---|
200 - OK |
요청이 성공했습니다 (성공적인 HTTP 요청의 표준 응답). |
400 - Bad Request |
요청에 클라이언트 오류가 있어 요청을 처리할 수 없습니다. |
401 - Unauthorized |
요청에 잘못된 사용자 인증 정보가 포함되어 있습니다. |
403 - Forbidden |
요청이 수신되고 이해되었지만 사용자에게 요청을 실행할 권한이 없습니다. |
404 - Not Found |
요청된 페이지를 찾을 수 없습니다. |
429 - Too Many Requests |
API에 대한 요청이 너무 많습니다. |
500, 502, 503, 504 - Server Errors |
요청을 처리하는 중에 예기치 않은 오류가 발생합니다. |
400 오류
이러한 오류는 요청에 오류가 있음을 의미하며, 이는 종종 필수 매개변수가 누락되어 발생합니다.
badRequest
이 오류는 코드에서 다음 문제 중 하나로 인해 발생할 수 있습니다.
- 필수 필드 또는 매개변수가 제공되지 않았습니다.
- 제공된 값 또는 제공된 필드의 조합이 잘못되었습니다.
- 첨부파일이 잘못되었습니다.
다음 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 오류
이러한 오류는 요청에 유효한 액세스 토큰이 포함되어 있지 않음을 의미합니다.
authError
이 오류는 사용 중인 액세스 토큰이 만료되었거나 잘못된 경우에 발생합니다. 이 오류는 요청된 범위에 대한 승인이 누락되어 발생할 수도 있습니다. 다음 JSON 샘플은 이 오류를 나타냅니다.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
이 오류를 해결하려면 장기 갱신 토큰을 사용하여 액세스 토큰을 새로고침하세요. 클라이언트 라이브러리를 사용하는 경우 토큰 새로고침이 자동으로 처리됩니다. 실패하면 사용자 인증 및 승인 알아보기에 설명된 대로 OAuth 흐름을 통해 사용자를 안내합니다.
Gmail 한도에 관한 자세한 내용은 사용량 한도를 참고하세요.
403 오류
이러한 오류는 사용량 한도를 초과하거나 사용자에게 올바른 권한이 없는 경우에 발생합니다. 원인을 확인하려면 반환된 JSON의 reason 필드를 평가하세요. 이 오류는 다음과 같은 상황에서 발생합니다.
- 인증된 사용자의 도메인 내에서 앱을 사용할 수 없습니다.
- 일일 한도를 초과했습니다.
- 사용자 비율 한도를 초과했습니다.
- 프로젝트 비율 한도를 초과했습니다.
자세한 내용은 사용량 한도를 참고하세요.
dailyLimitExceeded
이 오류는 프로젝트의 API 한도에 도달했을 때 발생합니다. 다음 JSON 샘플은 이 오류를 나타냅니다.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
이 오류는 애플리케이션 소유자가 특정 리소스의 사용량을 제한하기 위해 할당량 한도를 설정한 경우에 표시됩니다. 이 오류를 해결하려면 Google Cloud 프로젝트에서 할당량을 늘리세요. 자세한 내용은 할당량 한도 관리를 참고하세요.
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 액세스를 허용하지 않는다고 사용자에게 알립니다.
- 사용자에게 도메인 관리자에게 문의하여 앱에 대한 액세스를 요청하도록 안내합니다.
rateLimitExceeded
이 오류는 사용자가 Gmail API의 최대 요청 비율에 도달했음을 나타냅니다. 이 한도는 요청 유형에 따라 다릅니다. 다음 JSON 샘플은 이 오류를 나타냅니다.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
이 오류를 해결하려면 다음을 시도해 보세요.
userRateLimitExceeded
이 오류는 사용자당 한도에 도달했을 때 발생합니다. 다음 JSON 샘플은 이 오류를 나타냅니다.
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
이 오류를 해결하려면 애플리케이션 코드를 최적화하여 요청 수를 줄이거나 지수 백오프를 사용하여 요청을 재시도하세요.
429 오류
429 '요청이 너무 많음' 오류는 일일 사용자당 한도(메일 전송 한도 포함), 대역폭 한도 또는 사용자당 동시 요청 한도로 인해 발생할 수 있습니다. 각 한도에 관한 정보는 다음과 같습니다. 하지만 각 한도는 실패한 요청을 재시도하거나 여러 Gmail 계정으로 처리를 분할하여 해결할 수 있습니다.
사용자당 한도는 어떤 이유로도 늘릴 수 없습니다. 한도에 관한 자세한 내용은 사용량 한도를 참고하세요.
메일 전송 한도
Gmail API는 표준 일일 메일 전송 한도를 적용합니다. 이러한 한도는 유료 Google Workspace 사용자와 평가판 gmail.com 사용자에게 다릅니다. 이러한 한도는 Google Workspace의 Gmail 전송 한도를 참고하세요.
이러한 한도는 사용자당 한도이며 API 클라이언트, 기본 또는 웹 클라이언트, SMTP MSA 등 사용자의 모든 클라이언트에서 공유됩니다. 이러한 한도를 초과하면 재시도 시간이 포함된 HTTP 429 '요청이 너무 많음: 사용자 비율 한도 초과 (메일 전송)' 오류가 반환됩니다. 일일 한도를 초과하면 요청이 수락되기 전에 여러 시간 동안 이러한 오류가 발생할 수 있습니다.
메일 전송 파이프라인은 복잡합니다. 사용자가 할당량을 초과하면 API가 429 오류 응답을 반환하기 시작하기 전에 몇 분 정도 지연될 수 있습니다. 200 응답이 이메일이 성공적으로 전송되었음을 의미한다고 가정할 수는 없습니다.
대역폭 한도
API에는 IMAP과 동일하지만 독립적인 사용자당 업로드 및 다운로드 대역폭 한도가 있습니다. 이러한 한도는 사용자의 모든 Gmail API 클라이언트에서 공유됩니다.
이러한 한도는 일반적으로 예외적이거나 악용되는 상황에서만 발생합니다. 이러한 한도를 초과하면 재시도 시간이 포함된 HTTP 429 '요청이 너무 많음: 사용자 비율 한도 초과' 오류가 반환됩니다. 일일 한도를 초과하면 요청이 수락되기 전에 여러 시간 동안 이러한 오류가 발생할 수 있습니다.
동시 요청
Gmail API는 사용자당 비율 한도 외에도 사용자당 동시 요청 한도를 적용합니다. 이 한도는 사용자에 액세스하는 모든 Gmail API 클라이언트에서 공유되며 API 클라이언트가 Gmail 사용자 편지함 또는 백엔드 서버에 과부하를 일으키지 않도록 합니다.
단일 사용자에 대해 많은 병렬 요청을 하거나 요청 수가 많은 일괄 처리를 전송하면 이 오류가 발생할 수 있습니다. Gmail 사용자 편지함에 동시에 액세스하는 많은 독립적인 API 클라이언트도 이 오류를 발생시킬 수 있습니다. 이 한도를 초과하면 HTTP 429 '요청이 너무 많음: 사용자에게 동시 요청이 너무 많음' 오류가 반환됩니다.
500, 502, 503, 504 오류
이러한 오류는 요청을 처리하는 중에 예기치 않은 서버 오류가 발생하는 경우에 발생합니다. 요청의 타이밍이 다른 요청과 겹치거나 전체 사이트가 아닌 Google 사이트의 단일 페이지에 대한 권한을 업데이트하려고 시도하는 등 지원되지 않는 작업에 대한 요청을 비롯한 다양한 문제로 인해 이러한 오류가 발생할 수 있습니다.
다음은 5xx 오류 목록입니다.
- 500 백엔드 오류
- 502 잘못된 게이트웨이
- 503 서비스를 사용할 수 없음
- 504 게이트웨이 시간 초과
backendError
이 오류는 요청을 처리하는 중에 예기치 않은 오류가 발생하는 경우에 발생합니다. 다음 JSON 샘플은 이 오류를 나타냅니다.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
이 오류를 해결하려면 지수 백오프를 사용하여 요청을 재시도하세요.
실패한 요청을 재시도하여 오류 해결
시간 간격을 늘려 실패한 요청을 주기적으로 재시도하여 비율 한도, 네트워크 볼륨 또는 응답 시간과 관련된 오류를 처리할 수 있습니다. 예를 들어 1초 후에 실패한 요청을 재시도한 다음 2초 후에 재시도하고 4초 후에 재시도할 수 있습니다. 이 메서드를 지수 백오프라고 하며, 대역폭 사용량을 개선하고 동시 환경에서 요청 처리량을 극대화하는 데 사용됩니다.
오류 발생 후 1초 이상 지나서 재시도 기간을 시작하세요.
할당량 한도 관리
프로젝트의 사용량 한도를 확인 또는 변경하거나 할당량 증가를 요청하려면 다음 단계를 따르세요.
- 프로젝트의 결제 계정이 아직 없는 경우 계정을 만듭니다.
- API 콘솔에서 API 라이브러리의 사용 설정된 API 페이지를 방문하여 목록에서 API를 선택합니다.
- 할당량 관련 설정을 확인하고 변경하려면 할당량을 선택합니다. 사용 통계를 확인하려면 사용량을 선택합니다.
자세한 내용은 할당량 보기 및 관리를 참고하세요.
일괄 요청
일괄 요청을 사용하는 것이 좋지만 배치 크기가 클수록 비율 제한이 발생할 가능성이 높습니다. 50개가 넘는 일괄 처리를 전송하는 것은 권장되지 않습니다. 요청을 일괄 처리하는 방법에 관한 자세한 내용은 일괄 요청을 참고하세요.