API referansı

Hata kodları

Başarısız istekler standart bir hata nesnesi döndürür. Kodu programınızda kullanın; mesaj metni değişebilir.

Hata nesnesi

{
  "ok": false,
  "error": {
    "code": "insufficient_credits",
    "message": "...",
    "field": null
  }
}

Kod	HTTP	Anlamı	Ne yapmalı
`invalid_media_id`	400	`media_id` yalnız rakamlardan oluşmalı.	Webhook'taki `data.media.media_id` değerini aynen kullanın.
`invalid_phone_number_id`	400	`phone_number_id` rakam değil (yol parametresi). Arama ve form uçlarında 422 döner.	`GET /numbers` yanıtındaki `phone_number_id` değerini kullanın.
`invalid_template_id`	400	Şablon kimliği geçersiz.	`GET /templates` yanıtındaki `id` değerini kullanın.
`invalid_api_key`	401	Anahtar geçersiz, süresi dolmuş, iptal edilmiş ya da IP izin listesi dışından çağrılmış.	Anahtarı ve IP kısıtını panelden kontrol edin; gerekirse yeni anahtar oluşturun.
`unauthorized`	401	`Authorization` başlığı yok.	`Authorization: Bearer vmk_live_...` başlığını ekleyin.
`insufficient_credits`	402	Mesaj kredisi yetersiz (yalnız canlı anahtar). `error.balance` döner.	Kredi paketi alın; `credit.low` olayına abone olun.
`call_permission_required`	403	Müşterinin arama izni yok.	Önce `POST /calls/permission-request` ile izin isteyin.
`insufficient_scope`	403	Anahtarda gerekli kapsam yok. `error.required_scope` ya da `error.required_scopes` döner.	Panelden anahtara kapsam ekleyin ya da uygun kapsamlı yeni anahtar oluşturun.
`test_mode_unsupported`	403	İşlem test anahtarıyla yapılamaz (numara ayırma, form yazma uçları).	`vmk_live_` anahtarı kullanın.
`test_only`	403	Uç yalnız test anahtarıyla çalışır (`POST /test/inbound`).	`vmk_test_` anahtarı kullanın.
`call_not_found`	404	Arama yok, size ait değil ya da test/canlı anahtar uyuşmuyor.	Aramayı başlatan anahtar türünü kullanın.
`endpoint_moved`	404	API yanlış adresten çağrıldı.	Taban adres olarak `https://api.verimerkezi.app/wa` kullanın.
`flow_not_found`	404	Form yok ya da size ait değil.	Meta arayüzünde oluşturduğunuz formlar için `phone_number_id` ekleyin.
`media_file_missing`	404	Kayıt var, dosya depoda yok.	Destek ekibine `X-Request-Id` ile bildirin.
`media_not_found`	404	Medya kaydı yok ya da başka hesaba ait.	Kendi hesabınızın `media_id` değerini kullanın.
`not_found`	404	Arama uçlarında geçersiz eylem adı.	Yalnız `pre_accept`, `accept`, `reject`, `terminate` kullanın.
`number_not_found`	404	Numara size ait değil ya da aktif değil.	`GET /numbers` ile numaranın durumunu kontrol edin.
`template_not_found`	404	Şablon bulunamadı.	Şablon kimliğini `GET /templates` ile doğrulayın.
`webhook_not_found`	404	Abonelik yok ya da size ait değil.	`GET /webhooks` ile kimliği doğrulayın.
`action_in_progress`	409	Aynı arama için başka bir eylem hâlâ işleniyor.	`retry_after` (2 sn) kadar bekleyip tekrar deneyin.
`call_action_conflict`	409	Aynı eylem farklı parametreyle uygulanmış.	İlk eylemin sonucunu kullanın.
`call_ended`	409	Arama sona ermiş.	Yeni aramayı bekleyin ya da başlatın.
`calling_not_enabled`	409	Numarada arama kapalı.	`PATCH /numbers/{id}/calling` ile `enabled: true` yapın.
`contact_exists`	409	Telefon zaten rehberde kayıtlı. `error.id` mevcut kişiyi verir.	Mevcut kişiyi kullanın ya da toplu eklemede `skip_duplicates: true` gönderin.
`duplicate_call`	409	Bu kişiyle zaten süren bir arama var (Meta 138003).	Mevcut aramanın durumunu `GET /calls` ile izleyin.
`flow_not_draft`	409	İşlem yalnız DRAFT formda yapılır.	Yayınlanmış form için yeni form oluşturun.
`history_completed`	409	Geçmiş aktarımı daha önce tamamlandı.	Yeniden başlatmanız gerekmez.
`history_declined`	409	Müşteri geçmiş aktarımını reddetti.	Aktarım bu numara için yeniden başlatılamaz.
`history_in_progress`	409	Geçmiş aktarımı zaten başlatılmış (benzer biçimde `history_requested`, `history_completed`, `history_declined`).	`GET /numbers/{id}/history-import` ile durumu izleyin.
`history_requested`	409	Geçmiş aktarımı zaten istendi; müşterinin onayı bekleniyor.	`GET /numbers/{phone_number_id}/history-import` ile durumu izleyin.
`history_window_expired`	409	Geçmiş aktarımının 24 saatlik penceresi kapandı.	Geçmiş için numarayı kaldırıp yeniden bağlayın.
`idempotency_in_progress`	409	Aynı `Idempotency-Key` ile bir istek hâlâ işleniyor.	`Retry-After` kadar bekleyip aynı anahtarla tekrar deneyin.
`invalid_action_for_direction`	409	Başlattığınız aramada yalnız `terminate` kullanılabilir.	`POST /calls/{id}/terminate` kullanın.
`meta_outcome_unknown`	409	İstek Meta'ya iletildi ama sonucu doğrulanamadı (`retryable: false`).	Aynı anahtarla tekrar göndermeyin; durum olayını bekleyin ya da `GET /messages` ile kontrol edin.
`number_detached`	409	Numara hesabınızdan ayrılmış. Hata nesnesinde `phone_number_id` ve `detached_at` de döner.	Numarayı panelden yeniden bağlayın.
`waba_missing`	409	Numaranın işletme hesabı (WABA) bilgisi eksik; form işlemi yapılamaz.	Numarayı panelden yeniden bağlayın ya da destekle iletişime geçin.
`webhook_url_exists`	409	Bu adrese zaten aktif bir abonelik var. `existing_id` döner.	Mevcut aboneliği `PATCH` ile güncelleyin.
`template_exists`	409	Aynı WABA'da aynı ad ve dilde şablon zaten var (`field: name`, `template_id`).	Mevcut şablonu düzenleyin (`POST /templates/{id}`) ya da farklı ad / dil kullanın.
`template_not_editable`	409	Şablon düzenlenemez: durum `APPROVED` / `REJECTED` / `PAUSED` dışında ya da Meta'ya hiç gönderilmemiş (`status` döner).	Durum uygun olunca düzenleyin; `GET /templates/{id}` yanıtındaki `edit_limit.editable` alanına bakın.
`media_too_large`	413	Dosya türün Meta sınırını aşıyor (`max_bytes` döner).	Dosyayı küçültün; sınırlar için Medya rehberine bakın.
`media_invalid_format`	415	Desteklenmeyen dosya türü (içerik doğrulanır).	Desteklenen türlerden birine dönüştürün.
`unsupported_media_type`	415	Yükleme isteği `multipart/form-data` değil.	`-F file=@...` biçiminde gönderin.
`range_not_satisfiable`	416	İstenen bayt aralığı geçersiz.	`Range` başlığını dosya boyutuna göre düzeltin.
`calling_disabled_quality`	422	Meta kalite nedeniyle aramayı geçici kapattı (Meta 138014, `retryable: true`).	Bir süre sonra tekrar deneyin.
`calling_messaging_limit_too_low`	422	Günlük mesaj limiti 2.000'in altında (Meta 138015).	Mesajlaşma limitinizi yükseltin.
`calling_not_available_in_country`	422	Alıcının ülkesinde işletme araması yok.	Bu alıcıyı arayamazsınız.
`calling_not_supported_for_number`	422	Numara coexistence ya da Cloud API dışı; arama açılamaz (Meta 141000).	Aramayı ayrı bir API numarasında açın.
`calling_outbound_unavailable`	422	İşletme başlatmalı arama bu numara/ülkede yok (Meta 138013).	Gelen aramalarla çalışın.
`calling_prerequisites_unmet`	422	Numaranın teknik önkoşulları karşılanmıyor (Meta 138018).	Meta Business Suite'te numara ayarlarını kontrol edin.
`coexistence_readonly_profile`	422	Coexistence numarasında profil API ile güncellenemez.	Profili telefondaki WhatsApp Business uygulamasından güncelleyin.
`deregister_not_supported`	422	Meta'dan numara kaldırma bu sürümde yok.	`deregister_meta` göndermeyin.
`header_media_fetch_failed`	422	Şablon başlık medyası indirilemedi (`header_media_url`; `POST /templates/media` için `url` / `media_id`).	`header_media_url` adresinin herkese açık olduğundan emin olun.
`history_failed`	422	Geçmiş aktarımı başarısız oldu.	Destekle iletişime geçin.
`history_not_applicable`	422	Numara coexistence değil; geçmiş aktarımı yok.	Yalnız coexistence numaralarda kullanın.
`history_not_found`	422	Bu numara için geçmiş aktarımı kaydı yok.	Numaranın coexistence ile bağlandığını kontrol edin.
`idempotency_key_conflict`	422	Aynı `Idempotency-Key` farklı bir gövdeyle kullanılmış.	Her farklı istek için yeni anahtar üretin.
`invalid_contacts`	422	Kişi kartı mesajı hatalı: kart sayısı 1–20 dışında ya da `name.formatted_name` eksik.	`error.field` alanındaki kartı düzeltin.
`invalid_context`	422	`context.message_id` geçerli bir `wamid` değil.	Webhook'taki `data.wamid` değerini kullanın.
`invalid_flow`	422	`POST /messages` içindeki `flow` nesnesi hatalı.	`error.field` alanını düzeltin.
`invalid_flow_id`	422	`flow_id` yalnız rakam olmalı.	Meta form kimliğini kullanın.
`invalid_flow_json`	422	Flow JSON geçersiz ya da 10 MB'ı aşıyor.	Flow JSON'u doğrulayın.
`invalid_interactive`	422	Etkileşimli mesajın `interactive` nesnesi hatalı ya da Meta sınırını aşıyor.	`error.field` alanındaki değeri Meta sınırlarına göre düzeltin.
`invalid_location`	422	Konum mesajında enlem/boylam eksik ya da aralık dışı, ad/adres çok uzun.	`error.field` alanındaki değeri düzeltin; enlem −90…90, boylam −180…180.
`invalid_media`	422	Medya nesnesi hatalı (`link`/`id` yok, `https` değil, `audio.voice` boolean değil, boş dosya).	Medya nesnesini düzeltin.
`invalid_name`	422	Kişi adı en az 2 karakter olmalı.	`name` alanını doldurun.
`invalid_period`	422	`period` geçersiz.	`7d`, `30d` ya da `90d` kullanın.
`invalid_phone`	422	Telefon numarası geçersiz.	Ülke koduyla, `+` olmadan gönderin (ör. `905550000000`).
`invalid_reaction`	422	`reaction.message_id` ya da `emoji` geçersiz.	Tek bir emoji ve geçerli `wamid` gönderin.
`invalid_request`	422	Zorunlu alan eksik ya da biçim hatalı. `error.field` sorunlu alanı belirtir.	İstek gövdesini referanstaki alanlarla karşılaştırın.
`invalid_sdp`	422	SDP boş ya da geçersiz.	WebRTC ucunuzdan geçerli bir SDP üretin.
`invalid_since`	422	`since` ISO 8601 değil ya da izinli aralık dışında.	Örn. `2026-10-09T00:00:00Z`; mesajlarda 90, yeniden teslimde 7 gün sınırı.
`invalid_template_flow_button`	422	Şablon form butonu parametresi hatalı.	`sub_type: "flow"` buton biçimine uyun.
`invalid_webhook`	422	Webhook adresi `https`/genel değil ya da olay listesi boş/geçersiz.	Geçerli olay adları ve genel bir `https` adres kullanın.
`meta_call_failed`	422	Meta arama isteğini başka bir nedenle reddetti.	`meta_code` ve `meta_message` alanlarına bakın.
`meta_error`	422	Meta isteği reddetti (okundu, profil). `meta_code` döner.	Meta hata koduna göre düzeltin.
`meta_flow_failed`	422	Meta form isteğini reddetti.	`validation_errors` alanını düzeltin.
`meta_send_failed`	422	Meta gönderimi reddetti. `meta_code` ve `meta_subcode` alanlarına bakın (`retryable: true`).	`meta_code: 131047` ise 24 saat penceresi kapalıdır; şablon kullanın.
`meta_upload_failed`	422	Meta dosyayı kabul etmedi. Şablon başlık örneği yüklemesinde `meta_*` alanları da döner.	Dosya türünü ve boyutunu kontrol edin.
`outside_service_window`	422	Arama izni isteği için 24 saatlik pencere kapalı.	Müşteri size yazdıktan sonra tekrar deneyin.
`receiver_cannot_receive_calls`	422	Alıcı arama alamıyor (Meta 138001).	Kişiye mesajla ulaşın; tekrar denemeyin (`retryable: false`).
`template_delete_failed`	422	Meta şablon silmeyi kabul etmedi (ör. `DISABLED` şablon silinemez; `meta_*` alanları döner).	Tekrar deneyin; sürerse destek ekibine bildirin.
`template_edit_failed`	422	Meta şablon düzenlemesini kabul etmedi (`meta_*` alanları döner).	Meta'nın sebebine (`meta_user_message`) göre bileşenleri düzeltin.
`template_invalid`	422	Şablon Meta kurallarına aykırı; Meta'ya gönderilmedi.	`message` alanındaki kuralı düzeltin; `POST /templates/validate` ile önceden deneyin.
`template_not_in_waba`	422	Şablon gönderen numaranın WABA'sında yok ya da onaylı değil (Meta 132001).	Şablonun aynı WABA'da `APPROVED` olduğundan emin olun.
`template_rejected`	422	Meta şablonu reddetti.	Meta'nın sebebine göre içeriği düzeltip tekrar gönderin.
`too_many`	422	Toplu eklemede 1000 sınırı aşıldı.	Listeyi 1000'lik parçalara bölün.
`upload_failed`	422	Dosya alınamadı.	Yüklemeyi tekrar deneyin.
`waba_required`	422	Birden çok WABA'nız var; hedef belirtilmedi.	`waba_id` gönderin.
`category_not_editable`	422	Onaylı şablonda kategori değiştirilemez.	Kategoriyi göndermeyin ya da `POST /templates/{id}/copy` ile yeni şablon açın.
`invalid_template_parameters`	422	`POST /messages` şablon gönderiminde URL düğme bileşeni kayıtlı şablon tanımına uymuyor (`field` yolu söyler). Meta'ya gönderilmez; yalnız şablon Veri Merkezi'nde kayıtlıysa denetlenir, `AUTHENTICATION` hariç.	Değişkenli URL butonu için `{type:"button", sub_type:"url", index:"0", parameters:[{type:"text", text:"<adres sonu>"}]}` gönderin; sabit adresli URL butonuna bileşen göndermeyin.
`business_call_limit`	429	Aynı kişiye 24 saatte yapılabilecek işletme araması sınırı doldu (Meta 138012).	24 saat sonra tekrar deneyin.
`call_rate_limited`	429	Arama sınırı aşıldı.	Bekleyip tekrar deneyin.
`concurrent_call_limit`	429	Eşzamanlı arama sınırına ulaşıldı (Meta 138002).	Süren bir arama bitince tekrar deneyin (`retryable: true`).
`permission_request_limited`	429	Aynı kişiye arama izni isteği sınırı (24 saatte 1, 7 günde 2).	Sınır dolunca tekrar deneyin.
`rate_limited`	429	Dakikalık istek sınırı aşıldı. `Retry-After` ve `error.retry_after` döner. 2.27.0: `error.scope` (`key`, `account`, `account_share`), `error.bucket` ve `X-RateLimit-Scope` başlığı hangi sınırın aşıldığını gösterir.	`Retry-After` saniye kadar bekleyin; isteklerinizi yayın.
`sync_rate_limited`	429	Şablon senkronu WABA başına dakikada 1.	`Retry-After` kadar bekleyin.
`template_edit_limit`	429	Şablon düzenleme sınırı doldu (onaylı şablon 24 saatte 1, 30 günde 10). `next_edit_at` ve `retry_after` (saniye) döner; Meta kaynaklıysa `meta_*` alanları da gelir.	`next_edit_at` zamanından sonra tekrar deneyin.
`erasure_failed`	500	KVKK silmesi tamamlanamadı.	Tekrar deneyin; işlem idempotenttir.
`media_path_invalid`	500	Medya kaydının dosya yolu geçersiz.	Destek talebinde `X-Request-Id` değerini paylaşın.
`media_unreadable`	500	Medya dosyası okunamadı.	Kısa süre sonra tekrar deneyin; sürerse destekle iletişime geçin.
`send_failed`	500	Gönderim sistem hatasıyla tamamlanamadı; kredi iade edildi.	Aynı `Idempotency-Key` ile güvenle tekrar deneyin.
`server_error`	500	Beklenmeyen sunucu hatası (arama, form, numara ayırma).	Üstel bekleme ile tekrar deneyin.
`test_inbound_failed`	500	Sahte gelen mesaj işlenemedi.	Tekrar deneyin.
`webhook_create_failed`	500	Abonelik oluşturulamadı.	Tekrar deneyin.
`call_connection_error`	502	Arama bağlantısı kurulamadı (Meta 138004).	Kısa bir beklemeden sonra tekrar deneyin (`retryable: true`).
`meta_unavailable`	502	Meta yanıt vermiyor (arama ve form uçları). Şablon uçlarında Meta'ya ulaşılamadığında da bu kod döner.	Üstel beklemeyle tekrar deneyin (`retryable: true`).
`meta_unexpected_response`	502	Meta işlemi kabul etti ama kimlik döndürmedi; sonuç belirsiz.	Aynı isteği tekrar göndermeyin; önce listeleyip durumu kontrol edin.
`sync_failed`	502	Meta şablon listesi alınamadı.	Bir süre sonra tekrar deneyin.
`feature_unavailable`	503	Özellik geçici olarak kullanılamıyor.	Kısa süre sonra tekrar deneyin.
`temporarily_unavailable`	503	Altyapı geçici olarak yoğun (ör. veritabanı bağlantısı kısa süre reddedildi). 2.27.0 öncesinde bu durumlar `500` dönebiliyordu.	`Retry-After` (5 sn) sonra aynı isteği tekrarlayın; gönderimde aynı `Idempotency-Key` kullanın.
`rate_limit_unavailable`	503	Hız sınırı servisi geçici olarak kullanılamıyor (gönderim uçları güvenli tarafta kalır).	`Retry-After` (5 sn) sonra tekrar deneyin.
`call_connect_timeout`	504	Arama bağlantısı zaman aşımına uğradı (Meta 138007).	Tekrar deneyin (`retryable: true`).