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
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ı).

DurumAnlamı
400Geçersiz istek: eksik ya da hatalı alan, bilinmeyen alan adı (validation_error).
401API anahtarı yok, geçersiz ya da iptal edilmiş (unauthorized).
403Kapsam yok (scope), plan izin vermiyor (plan_limit), rol yetmiyor (forbidden_role), e-posta doğrulanmamış (email_not_verified) ya da organizasyon askıda.
404Kayıt bulunamadı ya da bu anahtar erişemiyor (not_found).
409İşlem bu durumda yapılamıyor; kod nedeni söyler.
413Plan depolama kotası dolu (storage_quota_exceeded); görsel silin ya da planı yükseltin.
422İçerik politikasına takıldı (content_policy).
429Anahtar, 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.
502Kanal ya da dış servis hatası (channel_error).
503Arka plan işleri durmuş ya da servis geçici olarak kullanılamıyor.

Sık görülen kodlar

KodDurumNe yapılır
validation_error400Mesajdaki alanı düzeltin; yeniden denemeyin.
unauthorized401Anahtarı denetleyin ya da OAuth belirtecini yenileyin.
scope403Anahtara gereken kapsamı veren yeni anahtar oluşturun.
plan_limit403Plan sınırı ya da API erişimi: planı yükseltin.
forbidden_role403İşlem daha yüksek rol istiyor.
email_not_verified403Kampanya oluşturmak için anahtarı oluşturan kişi (OAuth'ta yetkiyi veren) e-postasını panelden doğrulamalı.
opted_out, consent_required403Kişinin iletişim izni yok; mesaj gönderilmez.
bot_plan_restricted403Bot 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_found404Kimliği ve anahtarın bot erişimini denetleyin.
idempotency_conflict409Aynı anahtar farklı gövdeyle kullanıldı; yeni anahtar üretin.
idempotency_in_progress409İlk istek sürüyor; Retry-After kadar bekleyin.
content_policy422Metni politikaya uygun hâle getirin.
rate_limited429Retry-After kadar bekleyip yeniden deneyin.
message_quota_exceeded429Aylık mesaj kotası doldu; Retry-After ayın sıfırlanmasına kalan süredir.
template_required, template_unsupported400WhatsApp 24 saat penceresi kapalı: onaylı şablonla gönderin; şablon yalnız WhatsApp'ta kullanılır.
invalid_api_key400Girilen dış sağlayıcı (AI) anahtarı doğrulanamadı; anahtarı denetleyin.
organization_suspended403Organizasyon askıya alınmış; API erişimi kapalıdır, destekle iletişime geçin.
limit_reached, webhook_limit, open_limit409Kaynak sınırı doldu; kullanılmayanı silin, sonuçlandırın ya da planı yükseltin.
feature_disabled409Özellik bu organizasyonda kapalı; panelden açın.
not_connected, channel_not_configured, bot_inactive409Bot kanala bağlı ya da etkin değil; panelden bağlayıp etkinleştirin.
https_required409Sunucu adresi HTTPS değil; Telegram webhook'u kurulamaz.
bot_removed, bot_permission409Telegram'da bot topluluktan çıkarılmış ya da yönetici değil; botu yeniden ekleyip yetki verin.
ai_not_configured409AI sağlayıcısı ya da anahtarı ayarlı değil; panelden AI ayarlarını tamamlayın.
message_not_retryable409Yalnız başarısız giden mesajlar en fazla 5 kez yeniden denenir.
campaign_locked, campaign_started, campaign_finished409Kampanya gönderime başladı ya da bitti; değiştirilemez, yeni kampanya oluşturun.
invalid_status, schedule_conflict, post_locked409Kaydın şu anki durumu bu işleme uygun değil; kaydı yeniden okuyup karar verin.
contact_exists, field_exists, shortcut_exists, already_member409Aynı kayıt zaten var; mevcut kaydı kullanın ya da güncelleyin.
media_in_use409Görsel kullanımda; önce kullanıldığı yerden kaldırın.
storage_quota_exceeded413Plan 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_denied409Sahip değiştirilemez ya da çıkarılamaz; atanan kişi ekipte olmalı ve botun sohbetlerine erişmeli.
webhook_inactive409Webhook kapalı; önce POST /api/v1/webhooks/{id}/enable ile açın.
ai_quota_exceeded429Aylık AI yanıt kotası doldu; ek paket alın ya da ay başını bekleyin.
ai_error, ai_provider_unreachable502AI sağlayıcısı yanıt vermedi; biraz sonra yeniden deneyin.
channel_error502Kanal 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ır
  • X-RateLimit-Remaining: penceredeki kalan istek
  • X-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.