Hataları çözme

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 uygulamanız, REST API'yi kullanırken karşılaşılabilecek 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`	İstekteki istemci hatası nedeniyle istek yerine getirilemiyor.
`401 - Unauthorized`	İstek geçersiz kimlik bilgileri içeriyor.
`403 - Forbidden`	İstek alındı ve anlaşıldı ancak kullanıcının isteği gerçekleştirme izni yok.
`404 - Not Found`	İstenen sayfa 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şur.

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 sağlanmadı.
Sağlanan değer veya sağlanan alanların bir 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. Bu hata, istenen kapsamlar için yetkilendirmenin eksik olmasından da kaynaklanabilir. 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 süreli yenileme jetonunu kullanarak erişim jetonunu yenileyin. İstemci kitaplığı kullanıyorsanız jeton yenileme işlemi otomatik olarak yapılır. 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.
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ı.

Daha fazla bilgi için Kullanım sınırları bölümüne bakın.

`dailyLimitExceeded`

Bu hata, projenizin API sınırına ulaşıldığı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, uygulamanın sahibi belirli bir kaynağın kullanımını sınırlamak için kota sınırı belirlediğinde gösterilir. 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'nin 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, kullanıcı başına sınıra ulaşıldığı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 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 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şılırsa 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ülür. Günlük sınırların aşılması, istek kabul edilmeden ö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.

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 "Çok fazla istek: Kullanıcı hızı sınırı aşıldı" hatası döndürülür. Günlük sınırların aşılması, istek kabul edilmeden önce saatlerce 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şılırsa HTTP 429 "Çok fazla istek: Kullanıcı için çok fazla eşzamanlı istek" hatası döndürülür.

500, 502, 503, 504 hataları

Bu hatalar, istek işlenirken beklenmeyen bir sunucu hatası oluştuğunda meydana gelir. Bir isteğ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 de dahil olmak üzere çeşitli sorunlar bu hatalara neden olabilir.

Aşağıda 5xx hatalarının listesi verilmiştir:

500 Arka uç hatası
502 Hatalı 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 dönemlerini 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 kullanmanız önerilir 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öndermeniz önerilmez. İstekleri toplu olarak gönderme hakkında bilgi edinmek için Toplu istekler bölümüne bakın.