Hata sözlüğü
Hata zarfı her uçta aynıdır: { "code": "…", "message": "…" } (+ 429'larda retryAfterSeconds). message insan içindir ve değişebilir; programatik davranışı yalnız `code` ve HTTP durumuna bağlayın.
Kodlar
| HTTP | code | Anlam / yapılacak |
|---|---|---|
| 401 | invalid_api_key | Anahtar yok, biçimsiz, bilinmiyor, iptal edilmiş veya IP allowlist dışı — tek biçim. Anahtarı ve IP'yi kontrol edin. |
| 403 | insufficient_scope | Anahtarın scope'u bu uca yetmiyor (send/read). |
| 403 | account_suspended | Hesap askıda. Anahtar geçerli — değiştirmeyin, destekle görüşün. |
| 404 | not_found | Kayıt yok veya başka hesabın (varlık sızdırılmaz). Şablon send-test'te: şablon veya kimlik bulunamadı. |
| 409 | invalid_status | Kampanya durum makinesi bu geçişe izin vermiyor (örn. tamamlanmış kampanyayı durdurmak). |
| 409 | identity_exists | Aynı kimlik değeri zaten kayıtlı. |
| 409 | identity_in_use | Kimlik kampanyada kullanılmış; silinemez. |
| 409 | idempotency_conflict | Aynı Idempotency-Key 24 saat içinde farklı gövdeyle kullanıldı — yeni anahtar üretin. |
| 413 | attachments_too_large | Tekil dosya veya mesajın toplam eki 20 MB'ı aşıyor. |
| 422 | validation_error | Genel alan doğrulama hatası (zorunlu alan, biçim, bilinmeyen olay tipi, customerRef biçimi, geçersiz export formatı, bozuk bastırma adresi…). |
| 422 | too_many_recipients | to > 50 (mesaj) veya recipients > 10.000 (kampanya). |
| 422 | too_many_emails | Bastırma eklemede tek istekte 1.000 adres sınırı aşıldı. |
| 422 | identity_not_found | from adresi hesabın kimlikleriyle eşleşmiyor. GET /identities ile kontrol edin. |
| 422 | identity_not_verified | Kimlik var ama doğrulanmamış — DNS kayıtlarını tamamlayın. |
| 422 | no_default_identity | from boş ve varsayılan kimlik tanımlı değil. |
| 422 | no_valid_recipients | Elemeler sonrası geçerli to alıcısı kalmadı; kredi düşmedi. |
| 422 | scheduling_not_supported | İşlemsel mesajda scheduledAt yok; kampanya ucunu kullanın. |
| 422 | no_unopened_recipients | resend-to-unopened: açmayan alıcı yok. |
| 422 | invalid_url | Webhook URL'i geçersiz (https değil / localhost / private IP / çözümlenemedi). |
| 422 | webhook_limit_reached | Hesap başına 3 webhook endpoint sınırı doldu. |
| 429 | rate_limited | Dakikalık istek sınırı aşıldı. Retry-After kadar bekleyin. |
| 429 | daily_cap | Hesabın günlük gönderim tavanı aşıldı. Retry-After TR gece yarısına kadardır. |
| 502 | send_failed | Sağlayıcı mesajı kabul etmedi; kredi iade edildi (test/send-test'te kredi zaten düşmez). Daha sonra yeniden deneyin. |
Ret gerekçeleri (HTTP hatası değil)
200 yanıtın rejected[].reason alanında görünen değerler — istek başarılıdır, yalnız o alıcı elenmiştir:
| reason | Anlam |
|---|---|
invalid_syntax | Adres sentaksı geçersiz. |
mx_fail | MX ön doğrulaması başarısız. |
suppressed | Adres bastırma listesinde (işlemsel yolda yalnız campaign_and_transactional kapsamı süzer). |
quota | Kredi yetersiz — HTTP 200, kredi düşmez, messageId yazılmaz. |