Gmail API, iki düzeyde hata bilgisi döndürür:
- Üstbilgideki 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 uygulamaları, REST API kullanılırken karşılaşılabilecek tüm hataları yakalamalı ve işlemelidir. Bu kılavuzda, belirli API hatalarının nasıl çözüleceğiyle ilgili talimatlar verilmektedir.
400 hatasını düzeltme: Hatalı istek
Bu hata, kodunuzdaki şu hatalardan kaynaklanabilir:
- Zorunlu bir alan veya parametre sağlanmadı.
- Sağlanan değer veya sağlanan alanların bir kombinasyonu geçersiz.
- Ek geçersiz.
Aşağıda bu hatanın örnek bir JSON gösterimi verilmiştir:
{
"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 hatasını düzeltme: Geçersiz kimlik bilgileri
401 hatası, kullandığınız erişim jetonunun süresinin dolduğunu veya jetonun geçersiz olduğunu gösterir. Bu hata, istenen kapsamlar için yetkilendirmenin eksik olmasından da kaynaklanabilir. Bu hatanın JSON gösterimi aşağıda verilmiştir:
{
"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 süreli 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ı Gmail ile Uygulamanızı Yetkilendirme bölümünde 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 hatasını düzeltme: Kullanım sınırı aşıldı
Kullanım sınırı aşıldığında veya kullanıcının doğru ayrıcalıkları olmadığında 403 hatası oluşur. Hatanın türünü belirlemek için döndürülen JSON'un reason alanını değerlendirin. Bu hata aşağıdaki durumlarda ortaya çıkar:
- Günlük sınır aşıldı.
- Kullanıcı hız sınırı aşıldı.
- Proje hız sınırı aşıldı.
- Uygulamanız, kimliği doğrulanmış kullanıcının alanında kullanılamaz.
Gmail sınırları hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.
403 hatasını düzeltme: Günlük sınır aşıldı
dailyLimitExceeded hatası, projeniz için ücretsiz API sınırına ulaşıldığını gösterir. Bu hatanın JSON gösterimi aşağıda verilmiştir:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"reason": "dailyLimitExceeded",
"message": "Daily Limit Exceeded"
}
],
"code": 403,
"message": "Daily Limit Exceeded"
}
}
Bu hatayı düzeltmek için:
- Google API Konsolu'nu ziyaret edin.
- Projenizi seçin.
- Kotalar sekmesini tıklayın.
- Ek kota isteyin. Daha fazla bilgi için Ek kota isteme başlıklı makaleyi inceleyin.
Gmail sınırları hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.
403 hatasını düzeltme: Kullanıcı hız sınırı aşıldı
userRateLimitExceeded hatası, kullanıcı başına sınıra ulaşıldığını gösterir. Aşağıda bu hatanın JSON gösterimi verilmiştir:
{
"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 veya istekleri yeniden deneyecek şekilde optimize etmeyi deneyin. İstekleri yeniden denemeyle ilgili bilgi için Hataları çözmek için başarısız istekleri yeniden deneme başlıklı makaleyi inceleyin.
Gmail sınırları hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.
403 hatasını düzeltme: Sıklık sınırı aşıldı
rateLimitExceeded hatası, kullanıcının Gmail API'nin maksimum istek hızına ulaştığını gösterir. Bu sınır, istek türüne göre değişir.
Bu hatanın JSON gösterimi aşağıda verilmiştir:
{
"error": {
"errors": [
{
"domain": "usageLimits",
"message": "Rate Limit Exceeded",
"reason": "rateLimitExceeded",
}
],
"code": 403,
"message": "Rate Limit Exceeded"
}
}
Bu hatayı düzeltmek için başarısız istekleri yeniden deneyin.
Gmail sınırları hakkında daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.
403 hatasını düzeltme: {appId} kimlikli uygulama, kimliği doğrulanmış kullanıcının alanında kullanılamaz
Kullanıcının alanıyla ilgili politika, uygulamanızın Gmail'e erişmesine izin vermediğinde domainPolicy hatası oluşur. Bu hatanın JSON gösterimi aşağıda verilmiştir:
{
"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:
- 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.
429 hatasını çözme: Çok fazla istek var
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 denemeye çalışarak veya işleme sürecini birden fazla Gmail hesabına bölerek çözülebilir. Kullanıcı başına sınırlar hiçbir nedenle artırılamaz. 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 kullanıcılar ve deneme gmail.com kullanıcıları için farklıdır. Bu sınırlar için Gmail'deki gönderme sınırları başlıklı makaleyi inceleyin.
Bu sınırlar kullanıcı başına olup API istemcileri, yerel/web istemcileri veya SMTP MSA olsun, kullanıcının tüm istemcileri tarafından paylaşılır. Bu sınırlar aşılırsa yeniden deneme süresiyle birlikte HTTP 429 Too Many Requests "User-rate limit exceeded" "(Mail sending)" hatası döndürülür.
Günlük sınırların aşılması, istek kabul edilmeden önce birkaç saat boyunca bu tür hatalara neden olabilir.
Posta gönderme işlem hattı 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. Bu nedenle, 200 yanıtı e-postanın başarıyla gönderildiği anlamına gelmez.
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, belirli bir kullanıcı için tüm Gmail API istemcileri arasında paylaşılır.
Bu sınırlara genellikle yalnızca istisnai veya kötüye kullanım durumlarında ulaşılır.
Bu sınırlar aşılırsa yeniden deneme süresiyle birlikte bir HTTP 429 Too Many Requests "Kullanıcı hızı sınırı aşıldı" hatası döndürülür.
Günlük sınırların aşılması durumunda, istek kabul edilmeden önce bu tür hataların birkaç saat boyunca görülebileceğini unutmayın.
Eşzamanlı İstekler
Gmail API, kullanıcı başına eşzamanlı istek sınırı (kullanıcı başına oran sınırına ek olarak) uygular. Bu sınır, belirli 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 hataya neden olabilir. Bu sınır aşılırsa HTTP 429 Too Many Requests
"Kullanıcı için çok fazla eşzamanlı istek" hatası döndürülür.
500 hatasını düzeltme: Arka uç hatası
İstek işlenirken beklenmeyen bir hata oluştuğunda backendError meydana gelir.
{
"error": {
"errors": [
{
"domain": "global",
"reason": "backendError",
"message": "Backend Error",
}
],
"code": 500,
"message": "Backend Error"
}
}
Bu hatayı düzeltmek için başarısız istekleri yeniden deneyin. Aşağıda 500 hatalarının listesi verilmiştir:
- 502 Hatalı Ağ Geçidi
- 503 Hizmet Kullanılamıyor
- 504 Ağ Geçidi Zaman Aşımı
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 üstel geri çekilme adı verilir. Bant genişliği kullanımını iyileştirmek ve eşzamanlı ortamlarda isteklerin işleme hızını en üst düzeye çıkarmak için kullanılır.
Yeniden deneme dönemlerini hatadan en az bir saniye sonra başlatın.
Kullanım sınırlarını görüntüleme veya değiştirme, kotayı artırma
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.
Toplu istekler
Toplu işleme kullanılması önerilir ancak daha büyük toplu işleme boyutları, sıklık sınırlamasına neden olabilir. 50'den fazla istek içeren toplu işlemler göndermeniz önerilmez. İstekleri gruplandırma hakkında bilgi için İstekleri gruplandırma bölümüne bakın.