Gmail API'si 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 işleneceğini 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ğine ilişkin talimatlar sağlanmaktadır.
400 hatasını çözme: Hatalı istek
Bu hata, kodunuzdaki şu hatalardan kaynaklanabilir:
- Zorunlu bir alan veya parametre sağlanmamış.
- Sağlanan değer veya sağlanan alanların bir kombinasyonu geçersiz.
- Ek geçersiz.
Aşağıda bu hataya ilişkin ö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ı çözme: Geçersiz kimlik bilgileri
401 hatası, kullandığınız erişim jetonunun süresinin dolmuş veya geçersiz olduğunu belirtir. Bu hata, istenen kapsamlar için eksik yetkilendirmeden de 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şlemini otomatik olarak işler. Bu başarısız olursa kullanıcıyı Uygulamanızı Gmail ile yetkilendirme bölümünde açıklandığı gibi OAuth akışına yönlendirin.
Gmail sınırları hakkında ek bilgi için Kullanım sınırları bölümüne bakın.
403 hatasını çözme: Kullanım sınırı aşıldı
Kullanım sınırı aşıldığında veya kullanıcı doğru ayrıcalıklara sahip olmadığında 403 hatası oluşur. Belirli bir hata türünü belirlemek için döndürülen JSON dosyasının reason alanını değerlendirin. Bu hata aşağıdaki durumlarda ortaya çıkar:
- Günlük sınır aşıldı.
- Kullanıcı oranı 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 ek bilgi için Kullanım sınırları bölümüne bakın.
403 hatasını çözme: Günlük sınır aşıldı
dailyLimitExceeded hatası, projeniz için hediye 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 iste. Daha fazla bilgi için Ek kota isteme bölümünü inceleyin.
Gmail sınırları hakkında ek bilgi için Kullanım sınırları bölümüne bakın.
403 hatasını çözme: Kullanıcı oranı sınırı aşıldı
userRateLimitExceeded hatası, kullanıcı başına sınıra ulaşıldığını gösterir. Bu hatanın JSON gösterimi aşağıda 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 istek yapacak veya yeniden deneme isteğinde bulunacak şekilde optimize etmeyi deneyin. İsteklerin yeniden denenmesi hakkında bilgi edinmek için Hataları çözmek için başarısız istekleri yeniden deneme bölümüne bakın.
Gmail sınırları hakkında ek bilgi için Kullanım sınırları bölümüne bakın.
403 hatasını çözme: Hız sınırı aşıldı
rateLimitExceeded hatası, kullanıcının Gmail API'nin maksimum istek hızına ulaştığını belirtir. Bu sınır, isteklerin 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 ek bilgi için Kullanım sınırları bölümüne bakın.
403 hatasını düzeltme: {appId} kimliğine sahip uygulama, kimliği doğrulanmış kullanıcının alanında kullanılamaz
Kullanıcının alan adı politikası, uygulamanızın Gmail'e erişmesine izin vermediğinde bir 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ıyı, uygulamanızın Gmail'e erişmesine izin vermediği konusunda bilgilendirin.
- Kullanıcıdan, uygulamanız için erişim istemek üzere alan yöneticisi ile iletişime geçmesini isteyin.
429 hatasını çözme: Çok fazla istek var
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 429 "Çok fazla istek" hatası oluşabilir. Her bir sınıra ilişkin bilgiler aşağıda verilmiştir. Ancak her sınır, başarısız istekleri yeniden denenerek veya işlemeyi 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ı bölümüne bakın.
Posta gönderme sınırları
Gmail API'de standart günlük posta gönderme sınırları uygulanır. Bu sınırlar ödeme yapan Google Workspace kullanıcılar ve deneme sürümü gmail.com kullanıcıları için farklıdır. Bu sınırlar için Google Workspaceiçindeki Gmail gönderme sınırları başlıklı makaleyi inceleyin.
Bu sınırlar kullanıcı başınadır ve API istemcileri, yerel/web istemcileri veya SMTP MSA'sı olsun, kullanıcının tüm istemcileri tarafından paylaşılır. Bu sınırlar aşılırsa HTTP 429 Too Many Requests "Kullanıcı oranı sınırı aşıldı" "(Posta gönderme)" hatası, yeniden deneme süresi boyunca 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 ardışık düzeni karmaşıktır: Kullanıcı kotasını aştığında, API'nin 429 hata yanıtı döndürmeye başlamasından önce birkaç dakikalık bir gecikme yaşanabilir. Dolayısıyla, 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 kullanıcı başına yükleme ve indirme bant genişliği sınırları vardır. Bu sınırlar IMAP'ye eşit ancak ondan bağımsızdır. Bu sınırlar, belirli bir kullanıcı için tüm Gmail API istemcileri arasında paylaşılır.
Bu sınırlar genellikle yalnızca istisnai veya kötüye kullanım amaçlı durumlarda uygulanır.
Bu sınırlar HTTP 429 aşılırsa Too Many Requests
"Kullanıcı oranı sınırı aşıldı" hatası döndürülür ve yeniden deneme için belirli bir süre verilir.
Günlük sınırların aşılması, istek kabul edilmeden önce birkaç saat boyunca bu tür hatalara neden olabilir.
Eşzamanlı İstekler
Gmail API, kullanıcı başına eşzamanlı istek sınırı uygular (kullanıcı başına ücret sınırına ek olarak). 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 istek yapılması veya çok sayıda istek içeren gruplar göndermek bu hatayı tetikleyebilir. Gmail kullanıcı posta kutusuna eşzamanlı olarak erişen çok sayıda bağımsız API istemcisi de bu hatayı tetikleyebilir. 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ı çözme: Arka uç hatası
İstek işlenirken beklenmeyen bir hata oluştuğunda backendError oluşur.
{
"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 yer aldığı bir liste 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 deneyin
Hız sınırları, ağ hacmi veya yanıt süresi ile ilgili hataları işlemek için başarısız bir isteği artan bir süre boyunca düzenli aralıklarla yeniden deneyebilirsiniz. Örneğin, başarısız bir isteği bir saniye, iki saniye ve ardından dört saniye sonra yeniden deneyebilirsiniz. Bu yönteme üstel geri yükleme adı verilir ve 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.
Hatadan en az bir saniye sonra yeniden deneme sürelerini 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ını ziyaret edin 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şlemenin kullanılması önerilir. Bununla birlikte, daha büyük grup boyutlarının hız sınırlamasını tetikleme olasılığı yüksektir. 50'den fazla istek içeren grupların gönderilmesi önerilmez. İsteklerin nasıl toplu hale getirileceğiyle ilgili bilgi için İstekleri toplu hale getirme bölümüne bakın.