Bu rehberde: En sık karşılaşılan hataların nedenini ve çözümünü bulursunuz: izin süresi dolması, hız sınırı, bütçe aşımı, webhook doğrulama, plan limitleri, bekleyen ve atlanan çalıştırmalar, ifade ve yayın hataları.
⏱ 15 dakika
Kısaca
Hatalar üç yerde görünür: çalıştırma ayrıntısında kutunun üstünde, entegrasyon kartında (durum rozeti) ve API yanıtında. Önce aşağıdaki hızlı tabloya bakın; ayrıntı için ilgili bölüme geçin.
Geliştirici notu: Kutu hataları
node.failedolayında, API hataları{ statusCode, error, message, code }gövdesinde gelir.
Hızlı tablo
| Hata / kod | Nerede | Çözüm özeti |
|---|---|---|
AUTH – token geçersiz | Entegrasyon, node | Yeniden bağla |
RATE_LIMIT – 429 | Node, API | Bekle, retry/backoff, sıklığı düşür |
budget_exceeded / budget.exceeded | Ajan, run, organizasyon | Bütçeyi artır, modeli ucuzlat, adımı daralt |
| Webhook doğrulama başarısız | Meta, Slack, Discord, Twilio | Herkese açık HTTPS URL, doğru verify token/secret |
MODEL_NOT_ALLOWED | Node, ajan | Plan katmanı; başka model seç |
PLAN_LIMIT | Tetikleyici, oluşturma | Plan yükselt veya kaynakları azalt |
Run WAITING takıldı | Çalıştırma | Onay ver / süre bekle / yeniden dene |
Node SKIPPED | Çalıştırma | Boş dal; normal veya merge kullan |
İfade undefined | Node | Node adı/handle/alan adı |
post.failed | Yayın | Medya, karakter, token |
INTEGRATION_MISSING | Doğrulama | Node'da hesap seç |
1. Kimlik doğrulama süresi doldu (AUTH)
Belirti: Entegrasyon kartı "Yeniden yetkilendirme gerekli"; node hatası IntegrationError { code: "AUTH" }; sağlayıcı kodları: Meta 190, Google invalid_grant, X 401, LinkedIn 401 REVOKED_ACCESS_TOKEN, Slack invalid_auth/token_revoked, Telegram 401, Twilio 20003, Hunter/Serper/Apollo 401.
Nedenler: refresh token süresi doldu (Google Testing modunda 7 gün, LinkedIn 60 gün), kullanıcı izni kaldırdı, parola/2FA değişti, uygulama secret'ı sıfırlandı, geçici token kullanıldı (WhatsApp 24 saatlik), izin kaldırıldı (Meta Data Use Checkup).
Çözüm: Entegrasyonlar → kart → Yeniden bağla (OAuth) veya Kimlik bilgileri → Güncelle ile yeni token (token/API key). integrationId değişmez; iş akışları düzelir. Başarısız yayınlar için yönetici Kuyruklar → publishing → Başarısızları yeniden dene. Önleme: Google uygulamasını production'a alın; kalıcı system user token kullanın; integration.error olayına Slack bildirimi bağlayın.
2. Hız sınırı (RATE_LIMIT, 429)
Belirti: node RATE_LIMIT ile başarısız; sağlayıcı kodları: Meta 4/17/32/613, WhatsApp 130429/131056, X 429, Google quotaExceeded/rateLimitExceeded, Slack ratelimited, Discord 429, Anthropic 429 rate_limit_error, OpenAI 429; OrqLabs API 429 RATE_LIMIT.
Nedenler: aynı hesaba çok hızlı yayın/mesaj, saatlik tetikleyicilerle GA4/GSC kotası, Serper/Tavily kredisi, LLM sağlayıcı TPM/RPM sınırı, API anahtarı 600 istek/dk.
Çözüm: node Ayarlar → Yeniden deneme (maxAttempts 3, backoffMs 30000; motor RATE_LIMIT'i retryable sayar ve üstel bekler). Broadcast perMinute düşürün; logic.loop + logic.wait ile aralık verin; saatlik GA4 sorguları yerine analytics.kpiCheck (StatDaily). LLM 429'da OrqLabs otomatik yeniden dener; sürekli ise BYOK anahtarınızın katmanını yükseltin. API istemcisinde Retry-After başlığına uyun.
3. Bütçe aşıldı
Üç ayrı durum:
| Durum | Belirti | Çözüm |
|---|---|---|
Ajan budget_exceeded | Ajan çalıştırması kısmi sonuçla bitti; node item'ında budgetExceeded: true | Node budgetUsd (varsayılan 2) artırın; maxSteps düşürün; economy model; görevi daraltın (depth: quick, pagesToAudit az) |
Run FAILED + budget.exceeded | İş akışı settings.budgetUsd toplamı aşıldı | Bütçeyi beklenen maliyetin 2-3 katına ayarlayın; hangi node'un pahalı olduğunu run ayrıntısında görün |
| Organizasyon aylık | Bildirim "Aylık bütçe aşıldı"; yeni LLM çağrıları BUDGET_EXCEEDED (429) | Ayarlar → Bütçeler artırın (plan tavanına kadar) veya plan yükseltin; ay başında sıfırlanır |
budget.warning (%80) olayını trigger.event ile yakalayıp önceden uyarı alın. Maliyet analizi: Ayarlar → Kullanım → groupBy=agent.
4. Webhook doğrulama başarısız
| Sağlayıcı | Belirti | Neden | Çözüm |
|---|---|---|---|
| Meta (WhatsApp/Messenger/Instagram) | "The callback URL or verify token couldn't be validated" | URL erişilemez, HTTP, verify token farklı, ngrok kapalı | PUBLIC_WEBHOOK_URL HTTPS ve herkese açık; token'ı Webhook bilgisi kartından kopyalayın |
| Meta POST | OrqLabs 401 "signature" | META_APP_SECRET yanlış | Platform yöneticisi .env düzeltir |
| Slack | "Your URL didn't respond with the value of the challenge parameter" | API erişilemez, SLACK_SIGNING_SECRET yanlış | Request URL'yi tekrar kaydedin; secret'ı eşleyin |
| Discord | "Interactions endpoint URL could not be verified" | Public Key yanlış, PING'e PONG dönmüyor | Public Key'i General Information'dan kopyalayın |
| Twilio | OrqLabs 401 | URL Twilio'dakiyle birebir aynı değil (imza URL'yi içerir) | Şema/port/sondaki / eşleştirin |
| Telegram | Mesaj gelmiyor | setWebhook başarısız (HTTPS/sertifika) | Entegrasyonu yeniden kaydedin; getWebhookInfo ile hata mesajını görün |
trigger.webhook | 401 | X-Webhook-Secret eşleşmiyor | Başlığı ekleyin |
trigger.webhook | 404 | İş akışı ACTIVE değil | Etkinleştirin |
Geliştirmede ngrok URL'si her yeniden başlatmada değişir; sağlayıcı konsolunu güncelleyin veya sabit alan adı kullanın.
5. Model plan tarafından izin verilmiyor (MODEL_NOT_ALLOWED)
Belirti: doğrulama hatası "Model X planınızda kullanılamaz"; çalıştırma başlamadan 422; GET /orgs/:orgId/models → allowed: false.
Nedenler: FREE planda balanced/flagship, STARTER'da flagship seçilmiş; yönetici modeli kapatmış (enabled: false); iş akışı başka plandaki organizasyondan kopyalanmış.
Çözüm: Node → Gelişmiş → Model'i boş bırakın (organizasyon varsayılanı) veya izinli bir model seçin; plan yükseltin. Model kapatılmışsa çalıştırma aynı katmanın en ucuz açık modeline düşer ve bildirim gelir; yalnızca açıkça seçilmiş kapalı model hata verir.
6. Plan limitine ulaşıldı (PLAN_LIMIT)
| Limit | Belirti | Çözüm |
|---|---|---|
activeWorkflows | Etkinleştir pasif, "aktif iş akışı limiti" | Başka bir iş akışını duraklatın; plan |
workflows | Yeni iş akışı oluşturulamıyor | Arşivleyin (ARCHIVED) |
runsPerMonth / agentRunsPerMonth | Tetikleyiciler çalışmıyor, bildirim "aylık çalıştırma kotası" | Ay başını bekleyin; sık tetikleyicileri seyrekleştirin; plan |
integrations | Bağla pasif | Kullanılmayanı silin |
projects, members | Oluşturma/davet reddedildi | Plan |
knowledgeDocs | Belge eklenemiyor | Belgeleri birleştirin |
conversationsPerMonth | Yeni konuşmalar açılmıyor, bildirim | Plan |
tokensPerMonth | LLM çağrıları reddediliyor | Plan; economy model |
Kalan kotalar Ayarlar → Plan sayfasında; GET /orgs/:orgId → limits ve usage.
7. Çalıştırma WAITING durumunda takıldı
Nedenler: utility.approval veya logic.wait (approval/reply) bekliyor (normal); onay 72 saat sonra otomatik reddedilecek; logic.wait (reply) müşteri yanıtı bekliyor; Redis sıfırlandığı için resume işi kayboldu (yönetici).
Çözüm: Onaylar sayfasında kararı verin; bekleme süresini görmek için run ayrıntısında node.waiting.until. Zaman aşımı kısaltmak için timeoutHours. Kayıp resume için Yeniden dene (POST /runs/:id/retry) run'ı waitToken ile yeniden kuyruklar. Bekleyen run'lar eşzamanlılık ve kota tüketmez.
8. Node SKIPPED
Node'a hiç item gelmediğinde SKIPPED olur: logic.if bir dala item yönlendirmedi, logic.filter hepsini eledi, data.rss onlyNew yeni öğe bulmadı, social.getComments yeni yorum yok. Hata değildir. İki dalı birleştirmek için logic.merge (append); boş durumda da çalışması gereken node için önce utility.noop ile birleştirme yerine logic.merge waitBoth. Ajan node'ları boş girdiyle çalışmaz (maliyet oluşmaz).
9. İfade hataları
| Belirti | Neden | Çözüm |
|---|---|---|
Alan boş / undefined | Yanlış alan adı, $json.body.x yerine $json.x (webhook gövdesi body altında) | fx yardımcısıyla önceki çıktıyı inceleyin |
| "Unknown node" doğrulama hatası | $node["Ad"] adı yanlış/büyük-küçük harf | Node adını kopyalayın |
| Dizi yerine dize | Tek {{ }} etrafında boşluk/metin var | Parametreyi yalnızca {{ … }} yapın |
false dalındaki node true verisini görmüyor | Dallar ayrıdır | Gerekli alanı data.set ile item'a taşıyın |
| Tarih biçimi | $now UTC ISO | $date(...), $today |
$env boş | Kiracılara kapalı | $vars veya entegrasyon |
10. Yayın hataları (post.failed)
| Platform | Sık hata | Çözüm |
|---|---|---|
| X | 403 duplicate content; 280 karakter | Metni değiştirin; kısaltın |
422 UGC medya; 401 token | Medya URL; yeniden bağla | |
| 9004 medya; 36003 oran; JPEG | Herkese açık JPEG, 4:5-1.91:1 | |
| 200 izin; 100 parametre | App Review; medya | |
| Threads | 500 karakter; container ERROR | Kısaltın; video kodek |
| TikTok | unaudited_client…; format | Denetim; H.264 |
| YouTube | quotaExceeded; private lock | Kota; uygulama doğrulaması |
| board/link zorunlu | Pano ve link |
onError: errorOutput ile error handle'ına bildirim bağlayın; retryable hatalar için retry.maxAttempts 3.
11. Bilgi bankası indeksleme başarısız
Belirti: belge FAILED, knowledge-index kuyruğunda hata "embedding key missing" veya OpenAI 401/429.
Neden: OpenAI anahtarı (platform OPENAI_API_KEY veya BYOK) yok/geçersiz; belge çok büyük; PDF şifreli.
Çözüm: anahtar ekleyin; belgeyi bölün (50 MB / 5.000 sayfa üst sınır); şifreyi kaldırın. Yönetici: Kuyruklar → knowledge-index → Yeniden dene.
12. Entegrasyon eksik (INTEGRATION_MISSING)
Doğrulama: "Node için hesap seçilmedi" veya "Bağlı hesap uygun sağlayıcıda değil". Node → Ayarlar → Hesap seçin; proje kapsamlı entegrasyonun iş akışının projesinde olduğundan emin olun. Ajanlar için opsiyoneldir (araç devre dışı kalır, tool_result isError).
13. API hata kodları
| HTTP | code | Anlamı / çözüm |
|---|---|---|
| 400 | VALIDATION_ERROR | message[] alan hatalarını okuyun; tarih ISO, enum değerleri büyük harf |
| 401 | UNAUTHORIZED | Anahtar/JWT yok, süresi dolmuş (JWT 15 dk → refresh) |
| 403 | FORBIDDEN | Başka organizasyon, rol yetersiz (VIEWER yazamaz), IP kısıtı |
| 403 | INSUFFICIENT_SCOPE | API anahtarı kapsamı |
| 403 | PLAN_FEATURE | BYOK FREE'de, flagship STARTER'da |
| 404 | NOT_FOUND | Yanlış id veya başka organizasyon |
| 409 | CONFLICT | Aynı slug/e-posta; aktif run sürüyor (concurrency); son açık model kapatılamaz |
| 422 | WORKFLOW_INVALID, MODEL_NOT_ALLOWED, INTEGRATION_MISSING, TEMPLATE_PARAM_MISMATCH | İş mantığı |
| 429 | RATE_LIMIT, PLAN_LIMIT, BUDGET_EXCEEDED | Bekle / plan / bütçe |
| 502/503 | UPSTREAM | Sağlayıcı hatası; yeniden deneyin |
| 500 | INTERNAL | Hata id'siyle destek |
14. Yönetici tarafı belirtiler
| Belirti | Bakılacak yer |
|---|---|
| Hiçbir iş akışı çalışmıyor | Kuyruklar: worker canlı mı (workerAlive), Redis bağlantısı |
| Tüm yayınlar başarısız | publishing kuyruğu hataları; sağlayıcı kesintisi |
| LLM çağrıları hep 401 | ANTHROPIC_API_KEY / OPENAI_API_KEY; GET /admin/health providers |
| Kiracılar OAuth yapamıyor | .env OAuth kimlik bilgileri; redirect URI'ler |
| SSE çalışmıyor | Proxy buffering/timeout |
Ayrıntı: Kuyruklar ve sistem sağlığı.
Sık sorulan sorular
Bir hatayı düzelttikten sonra çalıştırmayı baştan mı başlatmalıyım? Hayır. Çalıştırma ayrıntısında Yeniden dene başarısız kutudan devam eder.
"Yeniden yetkilendirme gerekli" ne demek? Hesabın izni süresi doldu veya kaldırıldı. Entegrasyon kartında Yeniden yetkilendir'e basın; iş akışları bozulmaz.
Hataları anında nasıl öğrenirim? Zil bildirimleri gelir. Slack için "iş akışı hatası" olayına bağlı bir bildirim iş akışı kurun.