Gmail API, iki düzeyde hata bilgisi döndürür:
- Başlıktaki HTTP hata kodları ve mesajları.
- Yanıt gövdesinde, hatanın nasıl ele alınacağını belirlemenize yardımcı olabilecek ek ayrıntılar içeren bir JSON nesnesi.
Gmail uygulamanız, REST API'yi kullanırken karşılaştığınız tüm hataları yakalamalı ve işlemelidir. Bu kılavuzda, belirli Gmail API hatalarının nasıl çözüleceği ile ilgili talimatlar verilmektedir.
HTTP durum kodu özeti
| Hata kodu | Açıklama |
|---|---|
200 - OK |
İstek başarılıdır (Bu, başarılı HTTP istekleri için standart yanıttır). |
400 - Bad Request |
Sunucu, istemci hatası nedeniyle isteği yerine getiremedi. |
401 - Unauthorized |
İstek geçersiz kimlik bilgileri içeriyor. |
403 - Forbidden |
Sunucu isteği aldı ve anladı ancak kullanıcının isteği gerçekleştirme izni yok. |
404 - Not Found |
İstenen kaynak bulunamadı. |
429 - Too Many Requests |
API'ye çok fazla istek gönderildi. |
500, 502, 503, 504 - Server Errors |
İstek işlenirken beklenmeyen bir hata oluştu. |
400 hataları
Bu hatalar, isteğin genellikle gerekli bir parametrenin eksik olmasından kaynaklanan bir hata içerdiği anlamına gelir.
badRequest
Bu hata, kodunuzdaki aşağıdaki sorunlardan herhangi biri nedeniyle oluşabilir:
- Zorunlu bir alan veya parametre eksik.
- Sağlanan bir değer veya alan kombinasyonu geçersiz.
- Ek geçersiz.
Aşağıdaki JSON örneği, bu hatanın bir gösterimidir:
{
"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."
}
}
Bu hatayı düzeltmek için message alanını kontrol edin ve kodunuzu buna göre ayarlayın.
401 hataları
Bu hatalar, isteğin geçerli bir erişim jetonu içermediği anlamına gelir.
authError
Bu hata, kullandığınız erişim jetonunun süresi dolduğunda veya jeton geçersiz olduğunda oluşur. İstenen kapsamlar için yetkilendirmenin olmaması da bu hataya neden olabilir. Aşağıdaki JSON örneği, bu hatanın bir gösterimidir:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "authError",
"message": "Invalid Credentials",
"locationType": "header",
"location": "Authorization",
}
],
"code": 401,
"message": "Invalid Credentials"
}
}
Bu hatayı düzeltmek için uzun ömürlü yenileme jetonunu kullanarak erişim jetonunu yenileyin. İstemci kitaplığı kullanıyorsanız jeton yenileme işlemi otomatik olarak gerçekleştirilir. Bu işlem başarısız olursa kullanıcıyı Kimlik doğrulama ve yetkilendirme hakkında bilgi başlıklı makalede açıklandığı gibi OAuth akışına yönlendirin.
Gmail sınırları hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.
403 hataları
Bu hatalar, kullanım sınırını aştığınızda veya kullanıcının doğru ayrıcalıklara sahip olmadığı durumlarda oluşur. Nedeni belirlemek için döndürülen JSON'un reason alanını değerlendirin. Bu hata aşağıdaki durumlarda oluşur:
- Uygulamanız, kimliği doğrulanmış kullanıcının alanında kullanılamaz.
- Proje, günlük sınırı aştı.
- Kullanıcı, hız sınırını aştı.
- Proje, hız sınırını aştı.
Daha fazla bilgi için Kullanım sınırları bölümüne bakın.
dailyLimitExceeded
Bu hata, projeniz API sınırına ulaştığında meydana gelir. Aşağıdaki JSON örneği, bu hatanın bir gösterimidir:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Bu hata, uygulama sahibi belirli bir kaynağın kullanımını sınırlamak için kota sınırı belirlediğinde oluşur. Bu hatayı düzeltmek için Google Cloud projesindeki kotayı yükseltin. Daha fazla bilgi için Kota sınırlarını yönetme başlıklı makaleyi inceleyin.
domainPolicy
Bu hata, kullanıcının alanıyla ilgili politika, uygulamanızın Gmail'e erişmesine izin vermediğinde oluşur. Aşağıdaki JSON, bu hatanın gösterimidir:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "domainPolicy",
"message": "The domain administrators have disabled Gmail apps."
}
],
"code": 403,
"message": "The domain administrators have disabled Gmail apps."
}
}
Bu hatayı düzeltmek için aşağıdakileri deneyin:
- Kullanıcıya, alanın uygulamanızın Gmail'e erişmesine izin vermediğini bildirin.
- Kullanıcıya, uygulamanıza erişim isteğinde bulunmak için alan yöneticisiyle iletişime geçmesini söyleyin.
rateLimitExceeded
Bu hata, kullanıcının Gmail API için maksimum istek oranına ulaştığını gösterir. Bu sınır, istek türüne göre değişir. Aşağıdaki JSON örneği, bu hatanın bir gösterimidir:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Bu hatayı düzeltmek için aşağıdakileri deneyin:
- Kota artışı isteyin.
- İsteği yeniden denemek için eksponansiyel geri yükleme kullanın.
userRateLimitExceeded
Bu hata, bir istek kullanıcı başına sınıra ulaştığında oluşur. Aşağıdaki JSON örneği, bu hatanın bir gösterimidir:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "userRateLimitExceeded",
"message": "User Rate Limit Exceeded"
}
],
"code": 403,
"message": "User Rate Limit Exceeded"
}
}
Bu hatayı düzeltmek için uygulama kodunuzu daha az istekte bulunacak şekilde optimize etmeyi deneyin veya isteği yeniden denemek için eksponansiyel geri yüklemeyi kullanın.
429 hataları
429 "Çok fazla istek" hatası, kullanıcı başına günlük sınırlar (posta gönderme sınırları dahil), bant genişliği sınırları veya kullanıcı başına eşzamanlı istek sınırı nedeniyle oluşabilir. Her sınıra ilişkin bilgileri aşağıda bulabilirsiniz. Ancak her sınır, başarısız istekleri yeniden deneyerek veya işleme sürecini birden fazla Gmail hesabına bölerek çözülebilir.
Kullanıcı başına sınırları artıramazsınız. Sınırlar hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.
Posta gönderme sınırları
Gmail API, standart günlük posta gönderme sınırlarını uygular. Bu sınırlar, ücretli Google Workspace kullanıcıları ve deneme sürümündeki gmail.com kullanıcıları için farklıdır. Bu sınırlar için Google Workspace'te Gmail'deki gönderme sınırları başlıklı makaleyi inceleyin.
Bu sınırlar kullanıcı başına olup API istemcileri, yerleşik veya web istemcileri ya da SMTP MSA olsun, kullanıcının tüm istemcileri tarafından paylaşılır. Bu sınırları aşarsanız API, yeniden deneme süresiyle birlikte bir HTTP 429 "Çok fazla istek: Kullanıcı hızı sınırı aşıldı (posta gönderme)" hatası döndürür. Günlük sınırların aşılması, sunucu isteği kabul etmeden önce birkaç saat boyunca bu hatalara neden olabilir.
Posta gönderme ardışık düzeni karmaşıktır: Kullanıcı kotasını aştığında API'nin 429 hata yanıtları döndürmeye başlaması birkaç dakika sürebilir. 200 yanıtının, e-postanın başarıyla gönderildiği anlamına geldiğini varsayamazsınız.
Bant genişliği sınırları
API'nin, IMAP ile aynı olan ancak ondan bağımsız olan kullanıcı başına yükleme ve indirme bant genişliği sınırları vardır. Bu sınırlar, bir kullanıcının tüm Gmail API istemcileri arasında paylaşılır.
Kullanıcılar genellikle bu sınırlara yalnızca istisnai veya kötüye kullanım durumlarında rastlar. Bu sınırları aşarsanız API, yeniden deneme süresiyle birlikte bir HTTP 429 "Çok fazla istek: Kullanıcı hızı sınırı aşıldı" hatası döndürür. Günlük sınırların aşılması, sunucu isteği kabul etmeden önce birkaç saat boyunca bu hatalara neden olabilir.
Eşzamanlı istekler
Gmail API, kullanıcı başına eşzamanlı istek sınırı (kullanıcı başına hız sınırına ek olarak) uygular. Bu sınır, bir kullanıcıya erişen tüm Gmail API istemcileri tarafından paylaşılır ve hiçbir API istemcisinin Gmail kullanıcı posta kutusunu veya arka uç sunucusunu aşırı yüklememesini sağlar.
Tek bir kullanıcı için çok sayıda paralel istekte bulunmak veya çok sayıda istek içeren toplu işlemler göndermek bu hatayı tetikleyebilir. Gmail kullanıcı posta kutusuna aynı anda erişen çok sayıda bağımsız API istemcisi de bu hatayı tetikleyebilir. Bu sınırı aşarsanız API, HTTP 429 "Çok fazla istek: Kullanıcı için çok fazla eşzamanlı istek" hatasını döndürür.
500, 502, 503, 504 hataları
Bu hatalar, istek işlenirken beklenmeyen bir sunucu hatası oluştuğunda meydana gelir. İsteğin zamanlamasının başka bir istekle çakışması veya Google Siteler'de izinleri sitenin tamamı yerine tek bir sayfa için güncellemeye çalışmak gibi desteklenmeyen bir işlem isteği gibi çeşitli sorunlar bu hatalara neden olabilir.
Aşağıda 5xx hatalarının listesi verilmiştir:
- 500 Arka uç hatası
- 502 Bozuk ağ geçidi
- 503 Hizmet kullanılamıyor
- 504 Ağ geçidi zaman aşımı
backendError
Bu hata, istek işlenirken beklenmeyen bir hata oluştuğunda meydana gelir. Aşağıdaki JSON örneği, bu hatanın bir gösterimidir:
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Bu hatayı düzeltmek için isteği yeniden denerken eksponansiyel geri yükleme kullanın.
Hataları çözmek için başarısız istekleri yeniden deneme
Hız sınırları, ağ hacmi veya yanıt süresiyle ilgili hataları gidermek için başarısız olan bir isteği artan bir süre boyunca düzenli olarak yeniden deneyebilirsiniz. Örneğin, başarısız olan bir isteği bir saniye sonra, iki saniye sonra ve dört saniye sonra yeniden deneyebilirsiniz. Bu yönteme eksponansiyel geri yükleme adı verilir ve bant genişliği kullanımını iyileştirmek, eşzamanlı ortamlarda isteklerin işleme hızını en üst düzeye çıkarmak için kullanılır.
Yeniden deneme sürelerini hatadan en az bir saniye sonra başlatın.
Kota sınırlarını yönetme
Projenizin kullanım sınırlarını görüntülemek, değiştirmek veya kotanızda artış talep etmek için şunları yapın:
- Projeniz için faturalandırma hesabınız yoksa hesap oluşturun.
- API Konsolu'nda API kitaplığının Etkin API'ler sayfasına gidin ve listeden bir API seçin.
- Kota ile ilgili ayarları görüntülemek ve değiştirmek için Kotalar'ı seçin. Kullanım istatistiklerini görüntülemek için Kullanım'ı seçin.
Daha fazla bilgi için Kotaları görüntüleme ve yönetme başlıklı makaleyi inceleyin.
Toplu istekler
Toplu istekler performansı artırabilir ancak daha büyük toplu boyutlar, sıklık sınırlamasına neden olabilir. 50'den fazla istek içeren toplu işlemler göndermeyin. İstekleri toplu olarak gönderme hakkında bilgi edinmek için Toplu istekler bölümüne bakın.