API, başarısız isteklerde uygun bir HTTP durum kodu ve makine tarafından okunabilir bir hata nesnesi döndürür. Bu sayfa hataları nasıl yorumlayacağınızı ve ne zaman yeniden deneyeceğinizi anlatır.
#Hata yanıtının yapısı
{
"ok": false,
"error": {
"code": "invalid_phone",
"message": "Geçersiz alıcı numarası (E.164 format gerekli).",
"field": "to"
}
}| Alan | Açıklama |
|---|---|
error.code | Makine tarafından okunabilir hata kodu. Mantığınızı bu alana göre kurun. |
error.message | Türkçe açıklama. Kullanıcıya gösterilebilir; metni değişebilir. |
error.field | Hata belirli bir alandan kaynaklanıyorsa alan adı (ör. to, text, audio.voice). |
Bazı hatalarda error içinde ek alanlar gelir:
| Alan | Ne zaman | ||||||||
|---|---|---|---|---|---|---|---|---|---|
retryable | Mesaj gönderimi, arama ve form hatalarında. İsteğin tekrar denenip denenemeyeceğini söyler. | ||||||||
meta_code, meta_subcode | Meta kaynaklı hatalarda Meta'nın kodu. Meta kaynaklı her hatada vardır; Meta'ya bağlanılamadıysa 0. meta_subcode metin olarak döner. Şablon uçlarında ayrıca meta_message, meta_user_title, meta_user_message ve fbtrace_id gelir. | ||||||||
retry_after | 429 ve 409 idempotency_in_progress yanıtlarında beklenecek saniye. | ||||||||
balance | 402 insufficient_credits yanıtında güncel bakiye. | ||||||||
required_scope | 403 insufficient_scope yanıtında gereken kapsam. | ||||||||
required_scopes | Birden çok kapsamdan birini kabul eden uçlarda (ör. GET /messages) kabul edilen kapsamların dizisi; required_scope ile birlikte gelir. | ||||||||
meta_message | Arama hatalarında Meta'nın açıklaması (en fazla 300 karakter). | ||||||||
phone_number_id, detached_at | 409 number_detached yanıtında ayrılan numara ve ayrılma zamanı. | ||||||||
max_bytes, type | POST /media 413 media_too_large yanıtında tür ve izin verilen en büyük boyut (POST /templates/media için format). | ||||||||
field | Şablon doğrulama hatalarında (422 invalid_request, 422 template_invalid, 409 template_exists) hatalı alanın yolu (ör. components[0].text, name). | ||||||||
next_edit_at, retry_after | 429 template_edit_limit yanıtında en erken düzenleme zamanı ve beklenecek saniye. | ||||||||
template_id | 409 template_exists yanıtında mevcut şablonun kimliği. | ||||||||
rate_limited, errors | POST /templates/sync kısmen başarısız olduğunda WABA bazında ayrıntı. | ||||||||
base_url, docs | 404 endpoint_moved yanıtında doğru taban adres ve doküman adresi. | ||||||||
existing_id | 409 webhook_url_exists yanıtında mevcut abonelik. | ||||||||
message_tr, action_tr | Tüm hata yanıtlarında: kısa Türkçe açıklama ve yapılacak adım (adım yoksa null). Kaynak: hata kodları sözlüğü (GET /meta/error-codes). | ||||||||
severity, category | Kod sözlükte varsa önem (info | warn | error | critical); Meta kaynaklı hatada kategori (recipient | template | account | rate | payment | other). |
meta_message, meta_user_message, meta_message_tr | Meta'nın ham (çoğunlukla İngilizce) metni yalnız bu alanlarda gelir; error.message her zaman Türkçedir. Arama ve form hatalarında meta_message_tr Türkçe karşılıktır. |
401, 429 ve 503 yanıtlarının gövdesinde şu an ok alanı yoktur; yalnız error nesnesi döner. Başarıyı ok alanıyla değil, HTTP durum koduyla belirleyin. Bilmediğiniz ek alanları yok sayın.#HTTP durum kodları
| Durum | Anlamı |
|---|---|
200, 201, 202 | Başarılı. 202, işlemin kabul edildiğini gösterir. |
206, 304 | Medya indirmede kısmi içerik ve değişmemiş dosya. |
400 | Yol parametresi hatalı (ör. invalid_media_id). |
401 | Anahtar yok ya da geçersiz. |
402 | Mesaj kredisi yetersiz. |
403 | Kapsam yetersiz ya da işlem bu anahtar türüyle yapılamaz. |
404 | Kaynak yok ya da size ait değil. |
409 | Çakışma: kayıt zaten var, numara ayrılmış, işlem sürüyor ya da sonuç belirsiz. |
413, 415, 416 | Medya boyutu, türü ya da bayt aralığı hatası. |
422 | Doğrulama hatası ya da Meta reddi. |
429 | Hız sınırı aşıldı. |
500, 502, 503 | Sunucu ya da Meta tarafında geçici sorun. |
#Sık görülen hatalar
#422 meta_send_failed ve 24 saat penceresi
Müşteri size son 24 saat içinde yazmadıysa serbest metin, medya ve form mesajı Meta tarafından reddedilir. Yanıt 422 meta_send_failed ve meta_code: 131047 taşır. Bu durumda onaylı bir şablon gönderin. Ayrıntı: Mesaj gönderme.
#422 template_not_in_waba
Şablon, gönderen numaranın bağlı olduğu işletme hesabında (WABA) yok ya da onaylı değil. Şablonun aynı WABA'da APPROVED olduğundan emin olun. Bu hata retryable: false döner.
#402 insufficient_credits
Canlı anahtarda kredi bittiğinde döner. Kredi gönderimden önce ayrılır; gönderim başarısız olursa otomatik iade edilir. Bakiyeyi GET /credit/balance ile izleyin ve credit.low olayına abone olun.
#409 meta_outcome_unknown
İstek Meta'ya iletildi ama yanıt alınamadı (zaman aşımı ya da bağlantı kopması). Mesaj gitmiş olabilir. Aynı isteği tekrar göndermeyin. message.status.* olayını bekleyin ya da GET /messages ile kontrol edin. Idempotency-Key kullandıysanız aynı anahtarla yapılan tekrar Meta'ya ikinci kez gitmez.
#403 insufficient_scope
Anahtarda gereken kapsam yok. error.required_scope alanındaki kapsamı panelden anahtara ekleyin.
#Yeniden deneme stratejisi
| Durum | Yapılacak |
|---|---|
429 | Retry-After başlığındaki saniye kadar bekleyin, sonra tekrar deneyin. |
500, 502, 503 | Üstel bekleme ile tekrar deneyin (1 sn, 2 sn, 4 sn, 8 sn). |
retryable: true | Aynı Idempotency-Key ile güvenle tekrar deneyebilirsiniz. |
retryable: false | İsteği değiştirmeden tekrar denemeyin; önce sebebi giderin. |
409 idempotency_in_progress | Retry-After kadar bekleyip aynı anahtarla tekrar deneyin. |
409 meta_outcome_unknown | Tekrar göndermeyin; durum olayını bekleyin. |
Diğer 4xx | İsteği düzeltin; aynı isteği tekrar göndermek sonucu değiştirmez. |
Resmî SDK'lar 5xx ve 429 yanıtlarında en fazla 3 kez otomatik yeniden dener.
#Hataları kaydedin
Üretimde her hatayı en az şu bilgilerle kaydedin: zaman, uç nokta, HTTP durumu, error.code, error.field ve yanıttaki X-Request-Id başlığı. Destek talebinde X-Request-Id değerini paylaşın.
Tüm kodların listesi: Hata kodları.