Developer API xətaları və sorğu limitləri

Son yeniləmə: 11 noyabr 2026 · 6 dəq oxunur

Addımlar

1. 1

   Xəta forması

   Token, scope, limit və yol səhvləri eyni formadadır:

   {
     "error": {
       "code": "insufficient_scope",
       "message": "Bu əməliyyat üçün messages:send icazəsi lazımdır.",
       "required_scopes": ["messages:send"],
       "request_id": "3f9c2a1e-8b7d-4c6a-9e15-2d4b7a0c9f31"
     }
   }

   code sabitdir, kodunuzda ona baxın. message insan üçündür və dəyişə bilər, Accept-Language: en ilə ingiliscə gəlir. 403 cavabında WWW-Authenticate başlığı da olur. Endpoint-in öz yoxlamaları (məcburi sahə, yanlış dəyər) hələ köhnə formadadır, adətən 422 ilə: { "error": "..." } və ya { "message": "...", "attributes": [...] }. /oauth/* səhvləri OAuth formasındadır: { "error": "invalid_client" }.

2. 2

   Token və icazə xətaları

   • 401 invalid_token: token yoxdur, tanınmır və ya ləğv olunub. Başlığı yoxlayın: Authorization: Bearer clomni_pat_xxx.
   • 401 token_expired: müddəti bitib. Şəxsi token 30-365 gün, app tokeni 1 saat işləyir.
   • 403 insufficient_scope: tokendə scope yoxdur. required_scopes-a baxın, scope-u app-a əlavə edib review-a göndərin, təsdiqdən sonra yeni token yaradıb həmin scope-u seçin.
   • 403 endpoint_not_available: bu endpoint developer tokenlərinə açıq deyil, API reference-də yoxdur.
   • 403 app_not_approved: app-ın təsdiqlənmiş scope-u qalmayıb.
   • 403 app_suspended: Clomni app-ı dayandırıb və ya app arxivlənib. E-poçtdakı səbəbə baxın.
   • 403 app_owner_not_admin: app sahibi workspace-də artıq administrator deyil. Rol qaytarılanda işləyir.
   • 403 installation_owner_not_admin: public app-ı qoşan şəxs artıq administrator deyil, app-ı yenidən qoşmaq lazımdır.
   • 403 account_suspended: workspace dayandırılıb, yalnız workspace:read işləyir.
3. 3

   Digər xətalar

   • 400 invalid_request: yol və ya parametr səhvdir (məsələn limit 1-100 aralığından kənardır).
   • 402 ai_credit_spent: workspace-in AI krediti bitib (POST /ai_agents/{ai_agent_id}/ask). Avtomatik təkrar etməyin.
   • 404 not_found: obyekt yoxdur və ya başqa workspace-ə aiddir. 404 test_channel_missing: test kanalı yaradılmayıb.
   • 403 test_channel_webhook: test kanalına webhook ünvanı yazmaq olmaz. 403 sandbox_restricted: köhnə sandbox-da kənara göndərmək bağlıdır.
   • 409 conflict: eyni anda ikinci ixrac. 409 idempotency_key_reused: eyni Idempotency-Key fərqli gövdə ilə gəlib. 409 idempotency_key_in_progress: eyni açarlı sorğu hələ gedir.
   • 422: endpoint-in öz yoxlaması, məsələn eyni e-poçtla ikinci kontakt. Gövdəni düzəldin.
   • 500 internal_error: bizim tərəfdə səhv. Bir az sonra təkrar edin, təkrarlanırsa request_id ilə yazın.

   Mesajın göndərilməsi asinxrondur: WhatsApp-da 24 saatlıq pəncərə bağlı olanda və ya kanal qoşulu olmayanda sorğu qəbul olunur, sonra mesaj failed olur. Səbəb mesajın content_attributes.external_error sahəsindədir. WhatsApp QR-da yeni söhbət məhdudiyyəti (463) gələndə təkrar göndərməyin: hər cəhd məhdudiyyəti uzadır.

4. 4

   Nə vaxt təkrar etmək olar

   • 400, 401, 403, 404, 422: təkrar etməyin, əvvəl səbəbi düzəldin.
   • 429: Retry-After başlığındakı saniyə qədər gözləyin.
   • 500, 502, 503, 504 və şəbəkə xətası: artan fasilə ilə (1, 2, 4, 8 saniyə və təsadüfi əlavə), ən çox 5 dəfə.

   POST-u təkrar edəndə Idempotency-Key göndərin ki, mesaj iki dəfə getməsin.

5. 5

   Sorğu limitləri

   • Ümumi: token üzrə dəqiqədə 300 sorğu.
   • App-ın bütün tokenləri birlikdə: dəqiqədə 600 sorğu. Çox token yaratmaq limiti artırmır.
   • GET /sync/*: token üzrə dəqiqədə 60.
   • POST /conversations/{conversation_id}/messages: token üzrə dəqiqədə 60.
   • POST /oauth/token: client_id və IP üzrə dəqiqədə 20.
   • POST /exports: workspace üzrə eyni anda 1 iş, gündə 6.

   /v1/me və /v1/oauth/* xaric hər /v1 cavabında RateLimit-Limit, RateLimit-Remaining və RateLimit-Reset (saniyə) başlıqları olur. RateLimit-Remaining sıfıra yaxınlaşanda yavaşlayın.

6. 6

   429 alanda

   Limit keçiləndə cavab 429 rate_limited və Retry-After başlığı ilə gəlir. Bu müddət bitənə qədər eyni tokenlə sorğu göndərməyin. Başlıq yoxdursa artan fasilə ilə gözləyin. Siyahını hər dəqiqə yenidən çəkməyin: dəyişiklikləri webhook-larla alın, qaçanları updated_since ilə tutun. App tokenini hər sorğudan əvvəl yox, bitəndə yeniləyin. Daha yüksək limit lazımdırsa [email protected]ə app, endpoint, gözlənilən həcm və səbəbi yazın.

   API limiti kanalın öz limitini aradan qaldırmır: WhatsApp Business API nömrəsinin Meta tərəfindən gündəlik limiti və keyfiyyət reytinqi var, WhatsApp QR nömrəsi çox və ya istənməyən mesajdan bloklana bilər.