Błędy i idempotentność
Reaguj na kod błędu, nie na status. I zadbaj o to, by każda ponowna próba, która kosztuje, była bezpieczna.
Reaguj na kod, nie na status
Błędy zwracane są w postaci { "error": "<code>" }. Sam status nie wystarcza,
aby zdecydować, co zrobić — dwa błędy 403 mogą wymagać przeciwnych rozwiązań.
| Status | Code | Co to oznacza i co zrobić |
|---|---|---|
| 401 | invalid_key | Nieznany lub unieważniony klucz. Utwórz nowy; ponowna próba nigdy nie pomoże. |
| 403 | ip_not_allowed | Klucz ma listę dozwolonych adresów IP, a ten adres się na niej nie znajduje. Klucz jest poprawny — dodaj adres w developers.wasync.app/keys. Nie rotuj klucza. |
| 403 | insufficient_scope | Poświadczenie nie ma zakresu wymaganego przez ten endpoint. |
| 403 | forbidden_portal_kind | POST /connections na portalu Bitrix24. Połączenia na nim tworzy administrator portalu. |
| 400 | invalid_phone_number | phoneNumber musi zawierać same cyfry, bez wiodącego +. |
| 400 | invalid_webhook | Adres URL musi używać HTTPS i wskazywać publicznie dostępny host. |
| 402 | — | Licencja połączenia wygasła. Zobacz Licencje i okres próbny. |
| 409 | already_connected | Sesja jest aktywna; nie ma czego parować. |
| 409 | not_supported_for_provider | Operacja dostępna wyłącznie dla qr, wywołana na numerze cloud_api. Błąd trwały — nie ponawiaj. |
| 422 | recipient_not_on_whatsapp | WhatsApp nie znalazł konta odbiorcy. Sprawdź, czy numer jest w formacie międzynarodowym (najpierw kod kraju, bez wiodącego zera) i czy dana osoba korzysta z WhatsApp. Błąd trwały dla tego numeru — nie ponawiaj bez zmian. |
| 502 | send_failed | WhatsApp nie mógł dostarczyć wiadomości z powodu niezwiązanego z odbiorcą (sesja lub dostawca). Ponów próbę po krótkim opóźnieniu; jeśli problem się utrzymuje, sprawdź status połączenia. |
| 429 | warmup_limited | Godzinny limit rozgrzewania nowego numeru qr. Odczekaj kilka minut. |
| 429 | rate_limited | Limiter nadużyć. Jeśli jest nagłówek Retry-After, zastosuj się do niego; zawsze utrzymuj też domyślne opóźnienie. |
| 502 | pairing_code_unavailable | Zwykły wynik, nie awaria — skorzystaj z kodu QR. |
Nagłówek Retry-After nie jest gwarantowany przy każdym 409/429, dlatego nigdy
nie uzależniaj od niego swojego opóźnienia.
Idempotentność w POST /connections
Utworzenie połączenia uruchamia sesję WhatsApp i zajmuje płatny slot. Klient,
który przekroczy limit czasu i ponowi żądanie, utworzyłby drugie połączenie —
a Państwo po cichu zapłaciliby za dwa sloty dla jednego klienta. Opcjonalny
nagłówek Idempotency-Key zamyka tę lukę. Jest obsługiwany wyłącznie w
POST /connections; jeśli go pominiesz, zachowanie pozostaje takie jak dotąd.
Kluczem może być dowolny nieprzezroczysty ciąg do 255 znaków, przypisany do Twojego obszaru roboczego (dwaj partnerzy używający tego samego ciągu nigdy nie kolidują) i ważny przez 24 godziny od pierwszego żądania, które go użyło.
201 Created.200 OK oraz nagłówek odpowiedzi Idempotency-Replayed: true. Kod qr w tej odpowiedzi jest pobierany na nowo, a nie zapisany przy pierwszym utworzeniu: kody parowania zmieniają się mniej więcej co 20 sekund, więc powtórzony nieaktualny kod QR po prostu nie dałby się zeskanować. Traktuj 200 jako sukces, nie jako błąd.400 { "error": "idempotency_key_reuse" }. Porównanie opiera się na skrócie kanonicznego ciała, więc kolejność kluczy JSON nie ma znaczenia.409 { "error": "idempotency_in_progress" } z nagłówkiem Retry-After: 1. Zastosuj się do niego i ponów próbę z tym samym kluczem.Klucz dłuższy niż 255 znaków jest odrzucany z odpowiedzią
400 { "error": "idempotency_key_invalid" } — nigdy nie jest obcinany. Pusty
nagłówek lub zawierający wyłącznie białe znaki jest traktowany jak brak
nagłówka. Kształt ciała odpowiedzi nie zmienia się w żadnym z tych przypadków.
Generuj jeden klucz na jedną próbę wdrożenia klienta
Nowy UUID (crypto.randomUUID()) tworzony tuż przed wywołaniem i używany
tylko przez ponowne próby tego wywołania. Nie używaj jednego klucza na
proces, na klucz API, na dzień ani stałej wartości. Tak szeroki klucz sprawia,
że drugi wdrażany klient otrzyma z powrotem połączenie pierwszego klienta
zamiast własnego.
Idempotentność w wysyłce wiadomości
POST /messages przyjmuje idempotencyKey w ciele żądania (nie w
nagłówku). Zawsze go wysyłaj — jeden UUID na jedną logiczną wysyłkę.
- Przy każdym błędzie lub przekroczeniu limitu czasu ponów próbę z tym samym kluczem. Nowy klucz oznacza drugą prawdziwą wiadomość WhatsApp na czyimś telefonie.
- Przy
409 in_progressodpytuj z tym samym kluczem: jeśli jestRetry-After, zastosuj się do niego, w przeciwnym razie odczekaj około 5 s. - Wolna wysyłka nie oznacza nieudanej wysyłki. Ustaw limit czasu HTTP na co najmniej 180 s.