Gmail API iki düzeyde hata bilgisi döndürür:
- Üstbilgideki HTTP hata kodları ve mesajları.
- Yanıt gövdesinde, hatayı nasıl ele alacağınızı belirlemenize yardımcı olabilecek ek bilgiler içeren bir JSON nesnesi.
Gmail uygulamaları, REST API kullanılırken karşılaşılabilecek tüm hataları yakalayıp işlemelidir. Bu kılavuzda, belirli API hatalarının nasıl çözüleceğiyle ilgili talimatlar verilmiştir.
400 hatasını çözme: Hatalı istek
Bu hata, kodunuzdaki aşağıdaki hatalardan kaynaklanabilir:
- Gerekli bir alan veya parametre sağlanmadı.
- Sağlanan değer veya sağlanan alanların bir kombinasyonu geçersiz.
- Geçersiz ek.
Aşağıda bu hatanın örnek 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 dolduğunu veya geçersiz olduğunu gösterir. Bu hata, istenen kapsamlar için yetkilendirme eksikliğinden 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şlemi otomatik olarak gerçekleştirilir. Bu işlem başarısız olursa kullanıcıyı Uygulamanızı Gmail ile yetkilendirme bölümünde açıklandığı şekilde 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. Hata 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ı 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ılamıyor.
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ı, projenizin ü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 isteğinde bulunun. 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ı 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 gönderecek veya istekleri yeniden deneyecek şekilde optimize etmeyi deneyin. İstekleri yeniden deneme hakkında bilgi edinmek 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ı çözme: 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, 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 daha fazla bilgi için Kullanım sınırları başlıklı makaleyi inceleyin.
403 hatasını çözme: {appId} kimlikli uygulama, kimliği doğrulanmış kullanıcının alanında kullanılamıyor
Kullanıcının alanının politikası, 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ız için erişim isteğinde bulunmak üzere alan yöneticisiyle iletişime geçmesini söyleyin.
429 hatasını çözme: Çok fazla istek
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ırla ilgili bilgiler aşağıda verilmiştir. Ancak her sınır, başarısız isteklerini yeniden denemeye veya işlemleri birden fazla Gmail hesabı arasında bölme işlemine çalışarak çö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ü gmail.com kullanıcıları için farklıdır. Bu sınırlar için Google Workspace'te 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 yeniden deneme süresiyle birlikte HTTP 429 Too Many Requests "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 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ı birkaç dakikayı bulabilir. Bu nedenle, 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'de, IMAP'ye eşit ancak IMAP'den bağımsız 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ının tüm Gmail API istemcileri arasında paylaşılır.
Bu sınırlar genellikle yalnızca istisnai durumlarda veya kötüye kullanım amaçlı durumlarda aşılınır.
Bu sınırlar aşılırsa yeniden deneme süresiyle birlikte 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ı, 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ı (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üklemediğinden emin olur.
Tek bir kullanıcı için çok sayıda paralel istek yapılması veya çok sayıda istek içeren toplu istek gönderilmesi 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 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. 500 hatalarının listesi aşağıda 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 bir isteği düzenli aralıklarla artan bir süre boyunca tekrar deneyebilirsiniz. Örneğin, başarısız bir isteği bir saniye sonra, ardından iki saniye sonra ve daha sonra dört saniye sonra yeniden deneyebilirsiniz. Bu yönteme üstel geri çekilme adı verilir ve eşzamanlı ortamlarda bant genişliği kullanımını iyileştirmek ve isteklerin veri 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
Gruplandırma kullanılması önerilir ancak daha büyük grup boyutları hız sınırlamasını tetikleyebilir. 50'den fazla istek içeren toplu istekler gönderilmesi önerilmez. İstekleri nasıl gruplayacağınız hakkında bilgi edinmek için İstekleri gruplama başlıklı makaleyi inceleyin.