Geliştiriciler
Hatalar ve kurallar
Bütün uçlarda aynı çalışan kurallar: hata biçimi, hız sınırı, güvenli yeniden deneme, sayfalama, dil ve sürüm.
Hata biçimi
Hatalar JSON döner; code makine içindir ve dilden bağımsızdır, message kullanıcıya gösterilebilir.
HTTP/1.1 400 Bad Request
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1793955660
Content-Type: application/json
{ "error": { "code": "validation_error", "message": "to: Bu alan gerekli" } }HTTP durumu 400 (doğrulama; bilinmeyen alan adı mesajda belirtilir), 401 (kimlik), 403 (plan/kapsam), 404, 409 (işlem bu durumda yapılamaz), 422 (içerik politikası: content_policy), 429 (hız limiti veya aylık mesaj kotası: message_quota_exceeded), 502 (kanal hatası).
| Durum | Anlamı |
|---|---|
400 | Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error). |
401 | API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized). |
403 | Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda. |
404 | Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found). |
409 | İşlem bu durumda yapılamıyor; kod nedeni söyler. |
413 | Plan depolama kotası dolu (storage_quota_exceeded); görsel silin ya da planı yükseltin. |
422 | İçerik politikasına takıldı (content_policy). |
429 | Anahtar, kullanıcı ya da organizasyon istek sınırı (X-RateLimit-Scope) veya aylık mesaj kotası aşıldı; Retry-After başlığına uyun. |
502 | Kanal ya da dış servis hatası (channel_error). |
503 | Arka plan işleri durmuş ya da servis geçici olarak kullanılamıyor. |
Sık görülen kodlar
| Kod | Durum | Ne yapılır |
|---|---|---|
validation_error | 400 | Mesajdaki alanı düzeltin; yeniden denemeyin. |
unauthorized | 401 | Anahtarı denetleyin ya da OAuth belirtecini yenileyin. |
scope | 403 | Anahtara gereken kapsamı veren yeni anahtar oluşturun. |
plan_limit | 403 | Plan sınırı ya da API erişimi: planı yükseltin. |
forbidden_role | 403 | İşlem daha yüksek rol istiyor. |
email_not_verified | 403 | Kampanya oluşturmak için anahtarı oluşturan kişi (OAuth'ta yetkiyi veren) e-postasını panelden doğrulamalı. |
opted_out, consent_required | 403 | Kişinin iletişim izni yok; mesaj gönderilmez. |
bot_plan_restricted | 403 | Bot plan sınırının dışında kaldı; API gönderimi planı yükseltince açılır, panelden elle yanıt açıktır. |
not_found | 404 | Kimliği ve anahtarın bot erişimini denetleyin. |
idempotency_conflict | 409 | Aynı anahtar farklı gövdeyle kullanıldı; yeni anahtar üretin. |
idempotency_in_progress | 409 | İlk istek sürüyor; Retry-After kadar bekleyin. |
content_policy | 422 | Metni politikaya uygun hâle getirin. |
rate_limited | 429 | Retry-After kadar bekleyip yeniden deneyin. |
message_quota_exceeded | 429 | Aylık mesaj kotası doldu; Retry-After ayın sıfırlanmasına kalan süredir. |
template_required, template_unsupported | 400 | WhatsApp 24 saat penceresi kapalı: onaylı şablonla gönderin; şablon yalnız WhatsApp'ta kullanılır. |
invalid_api_key | 400 | Girilen dış sağlayıcı (AI) anahtarı doğrulanamadı; anahtarı denetleyin. |
organization_suspended | 403 | Organizasyon askıya alınmış; API erişimi kapalıdır, destekle iletişime geçin. |
limit_reached, webhook_limit, open_limit | 409 | Kaynak sınırı doldu; kullanılmayanı silin, sonuçlandırın ya da planı yükseltin. |
feature_disabled | 409 | Özellik bu organizasyonda kapalı; panelden açın. |
not_connected, channel_not_configured, bot_inactive | 409 | Bot kanala bağlı ya da etkin değil; panelden bağlayıp etkinleştirin. |
https_required | 409 | Sunucu adresi HTTPS değil; Telegram webhook'u kurulamaz. |
bot_removed, bot_permission | 409 | Telegram'da bot topluluktan çıkarılmış ya da yönetici değil; botu yeniden ekleyip yetki verin. |
ai_not_configured | 409 | AI sağlayıcısı ya da anahtarı ayarlı değil; panelden AI ayarlarını tamamlayın. |
message_not_retryable | 409 | Yalnız başarısız giden mesajlar en fazla 5 kez yeniden denenir. |
campaign_locked, campaign_started, campaign_finished | 409 | Kampanya gönderime başladı ya da bitti; değiştirilemez, yeni kampanya oluşturun. |
invalid_status, schedule_conflict, post_locked | 409 | Kaydın şu anki durumu bu işleme uygun değil; kaydı yeniden okuyup karar verin. |
contact_exists, field_exists, shortcut_exists, already_member | 409 | Aynı kayıt zaten var; mevcut kaydı kullanın ya da güncelleyin. |
media_in_use | 409 | Görsel kullanımda; önce kullanıldığı yerden kaldırın. |
storage_quota_exceeded | 413 | Plan depolama kotası dolu; görsel silin ya da planı yükseltin. Kullanım getUsage yanıtının storage alanında. |
member_not_changeable, member_not_removable, not_team_member, bot_access_denied | 409 | Sahip değiştirilemez ya da çıkarılamaz; atanan kişi ekipte olmalı ve botun sohbetlerine erişmeli. |
webhook_inactive | 409 | Webhook kapalı; önce POST /api/v1/webhooks/{id}/enable ile açın. |
ai_quota_exceeded | 429 | Aylık AI yanıt kotası doldu; ek paket alın ya da ay başını bekleyin. |
ai_error, ai_provider_unreachable | 502 | AI sağlayıcısı yanıt vermedi; biraz sonra yeniden deneyin. |
channel_error | 502 | Kanal hatası; Idempotency-Key ile yeniden deneyebilirsiniz. |
Hız sınırı
Anahtar başına dakikada 120 istek; geçersiz anahtarlar IP başına dakikada 60, kapsam ve plan 403'leri organizasyon başına dakikada 120 sayılır, MCP istekleri de aynı sınırlara girer. Ayrıca organizasyonun bütün anahtarları ve OAuth bağlantıları plana göre ortak bir dakikalık ve günlük (UTC) sınırı paylaşır; bu katmanda 429 yanıtı X-RateLimit-Scope başlığıyla aşılan katmanı (organization ya da organization_day) söyler.
X-RateLimit-Limit: dakikalık sınırX-RateLimit-Remaining: penceredeki kalan istekX-RateLimit-Reset: pencerenin sıfırlanacağı an (Unix saniye)Retry-After: 429 yanıtında beklenecek saniye; aylık kotada ayın sıfırlanmasına kalan süre
Hata yanıtları dahil yanıtlar bu başlıkları taşır. Art arda 429 alırsanız bekleme süresine uyun; hemen yeniden denemek sınırı uzatmaz ama istekleri boşa harcar.
import { Hiboty, HibotyHatasi } from "@hiboty/sdk";
const hiboty = new Hiboty({ apiKey: process.env.HIBOTY_API_KEY });
const botId = process.env.BOT_ID;
async function sendWithRetry(to, message) {
for (let attempt = 0; attempt < 3; attempt++) {
try {
return await hiboty.sendMessage({ bot_id: botId, to, message }, { idempotencyKey: `note-${to}` });
} catch (err) {
if (!(err instanceof HibotyHatasi) || err.status !== 429 || attempt === 2) throw err;
await new Promise((r) => setTimeout(r, (err.retryAfter ?? 1) * 1000));
}
}
}
console.log(await sendWithRetry("123456789", "Merhaba!"), hiboty.rateLimit);Güvenli yeniden deneme (Idempotency-Key)
Destekleyen uçlar başvuruda işaretlidir (POST /api/v1/messages, POST /api/v1/campaigns ve çoğu yazma ucu). Idempotency-Key başlığı 1-255 görünür ASCII karakterdir. Anahtar organizasyon ve uç başına 24 saat geçerlidir: aynı anahtar ve aynı gövdeyle ilk yanıt aynen döner (Idempotency-Replayed: true), mesaj ikinci kez gitmez ve kota iki kez düşmez. Farklı gövdede 409 idempotency_conflict, ilk istek sürerken 409 idempotency_in_progress ve Retry-After döner. 5xx ve 429 yanıtları saklanmaz; aynı anahtarla yeniden deneyebilirsiniz.
curl -X POST "https://hiboty.com/api/v1/messages" \
-H "Authorization: Bearer $HIBOTY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-10482" \
-d '{"bot_id":"3fa85f64-5717-4562-b3fc-2c963f66afa6","to":"123456789","message":"Merhaba!"}'Sayfalama
Liste uçları limit (1–200) ve cursor kabul eder; varsayılan ve üst sınır farklıysa başvuruda yazar. Yanıttaki next_cursor değerini cursor olarak aynen gönderin; son sayfada null döner. limit tam sayı değilse 400 döner. SDK'lerde paginate bu listelerin hepsini dolaşır.
curl "https://hiboty.com/api/v1/contacts?limit=50" -H "Authorization: Bearer $HIBOTY_API_KEY"
# { "data": [ ... ], "next_cursor": "eyJ0Ijoi..." }
curl "https://hiboty.com/api/v1/contacts?limit=50&cursor=eyJ0Ijoi" -H "Authorization: Bearer $HIBOTY_API_KEY"Dil
Hata mesajları varsayılan olarak Türkçedir; ?lang=en ya da Accept-Language: en ile İngilizce döner. Kod (code) alanı her zaman aynıdır. SDK'lerde lang seçeneğiyle belirlenir.
curl "https://hiboty.com/api/v1/bots?lang=en" -H "Authorization: Bearer $HIBOTY_API_KEY"
curl "https://hiboty.com/api/v1/bots" -H "Authorization: Bearer $HIBOTY_API_KEY" -H "Accept-Language: en"Sürüm politikası
API ve SDK'ler semantik sürümleme kullanır; güncel sürüm OpenAPI belgesindeki info.version değeridir. v1 adresi altında yalnız geriye uyumlu eklemeler yapılır: yeni uç, isteğe bağlı alan ya da yanıt alanı. İstemciniz yanıttaki bilinmeyen alanları yok saymalıdır. Alan kaldırma ya da anlam değiştirme yeni bir ana sürüm (v2) ile yapılır ve geçiş süresiyle önceden duyurulur. Hatalı kullanımı reddeden düzeltmeler (ör. yazım hatalı alanın 400 dönmesi) ara sürümde yayımlanabilir ve değişiklik notunda belirtilir.
Kanal webhook'ları
Telegram ve WhatsApp webhook'ları Hiboty tarafından otomatik kurulur ve imzayla doğrulanır. Olayları kendi sisteminize iletmek için giden webhook'ları kullanın.