Błędy i limity API e-mail: kody statusu, ponawianie i monitoring

Wysłanie jednego e-maila w wersji demo jest proste. Wysyłanie stu tysięcy miesięcznie na produkcji oznacza przygotowanie się na chwile, gdy coś pójdzie nie tak: unieważniony klucz, wygasła karta, miesiąc, który kończy się szybciej, niż zakładano, albo serwer pocztowy, który ma gorszy dzień.

Ten poradnik wyjaśnia każdą odpowiedź zwracaną przez endpoint wysyłki Inbixio, co Twój kod powinien z nią zrobić i jak obserwować dostarczanie po uruchomieniu.

Dwa etapy: przyjęcie, potem dostarczenie

Wywołanie POST /api/send-email/ przebiega w dwóch etapach:

1. Żądanie API. Inbixio sprawdza klucz, jego uprawnienia, subskrypcję, miesięczne zużycie i treść żądania. Jeśli wszystko się zgadza, zwraca 200 i dodaje wiadomość do kolejki.
2. Dostarczenie. Chwilę później Inbixio łączy się z Twoim serwerem SMTP i przekazuje mu wiadomość. Każda wiadomość jest zapisywana jako wysłana lub nieudana, a te wyniki zasilają liczby w Twoim panelu.

Zatem 200 oznacza „przyjęto do dostarczenia”, a nie „jest w skrzynce”. Problemy na etapie 1 wracają jako błędy HTTP, które Twój kod może obsłużyć. Problemy na etapie 2, np. błędne hasło SMTP, widać w panelu jako odsetek nieudanych dostarczeń. Inbixio podejmuje jedną próbę dostarczenia każdej wiadomości; nie ponawia nieudanych dostarczeń.

Każda odpowiedź i co z nią zrobić

Komunikaty błędów przychodzą w polu error w większości odpowiedzi, a w polu detail przy błędach uwierzytelniania, więc odczytuj oba:

const body = await res.json().catch(() => ({}));
const reason = body.error ?? body.detail ?? res.statusText;

Ponawiaj tylko to, co może się później udać

Ponowienie 401 sto razy nie sprawi, że klucz stanie się ważny; zapełni tylko logi. Podziel błędy na dwie grupy:

• Ponawiaj: błędy sieci, timeouty, odpowiedzi 5xx i 429 z rate limitu (ta z komunikatem w detail). Czekaj tyle, ile wskazuje nagłówek Retry-After, a w przeciwnym razie stosuj wykładniczy backoff z losowym rozrzutem (jitter) i zrezygnuj po kilku próbach.
• Nie ponawiaj: 400, 401, 402, 403 oraz 429 z miesięcznego limitu (ta z polami limit i sent). Te wymagają człowieka albo innego żądania. Loguj je wyraźnie i ustaw alerty na 401, 402 i 429 z miesięcznego limitu, bo zatrzymują całą Twoją pocztę.

// 5xx and the short-term rate limit can succeed later; the monthly limit (body has `limit`) can't.
const retryable = (status, body) => status >= 500 || (status === 429 && body.limit === undefined);

export async function sendWithRetry(payload, attempts = 4) {
  for (let i = 0; i < attempts; i++) {
    let res;
    try {
      res = await fetch('https://backend.inbixio.com/api/send-email/', {
        method: 'POST',
        headers: { 'X-API-Key': process.env.INBIXIO_API_KEY, 'Content-Type': 'application/json' },
        body: JSON.stringify(payload),
        signal: AbortSignal.timeout(15_000),
      });
    } catch (err) {
      if (i === attempts - 1) throw err; // network error or timeout: retry
    }
    if (res?.ok) return res.json();
    if (res) {
      const body = await res.json().catch(() => ({}));
      if (!retryable(res.status, body)) {
        throw new Error(`Inbixio ${res.status}: ${body.error ?? body.detail ?? res.statusText}`);
      }
    }
    const retryAfter = Number(res?.headers.get('Retry-After')) * 1000;
    const delay = retryAfter || Math.min(30_000, 1000 * 2 ** i) * (0.5 + Math.random()); // 0.5s–30s with jitter
    await new Promise((r) => setTimeout(r, delay));
  }
  throw new Error('Inbixio: gave up after retries');
}

O duplikatach: jeśli żądanie przekroczy limit czasu, mogło mimo to zostać przyjęte. Ponowienie może wtedy wysłać ten sam e-mail dwa razy. Przy paragonach i powiadomieniach jest to zwykle akceptowalne; tam, gdzie duplikat zdezorientowałby użytkowników, zapisuj wysłane wiadomości we własnej bazie danych i sprawdzaj ją przed ponowieniem.

Miesięczne limity

Każdy plan obejmuje określoną liczbę e-maili miesięcznie: 25 000 w planie Starter i 150 000 w planie Growth. Inbixio liczy e-maile pomyślnie wysłane w bieżącym miesiącu kalendarzowym. Po osiągnięciu limitu wysyłki zwracają 429 z Twoim limit i bieżącą liczbą sent, dopóki nie zacznie się kolejny miesiąc albo nie przejdziesz na wyższy plan.

Nie czekaj na 429:

• Strona API Keys (klucze API) pokazuje kartę Usage Limit (limit użycia) z liczbą wysłanych w tym miesiącu wiadomości na tle limitu Twojego planu.
• Ustaw sobie przypomnienie, by sprawdzić ją przy około 80% limitu, i zaplanuj zmianę planu przed dużym startem lub importem.
• Szacowanie wolumenu krok po kroku znajdziesz w artykule jak wybrać plan API e-mail.

Nieudane dostarczenia (etap 2)

Gdy API przyjęło wiadomość, ale Twój serwer SMTP ją odrzucił, liczy się to jako nieudane dostarczenie. Panel pokazuje wskaźnik Failed Deliveries (nieudane dostarczenia) z ostatnich 7 dni, a nie listę pojedynczych wiadomości, więc obserwuj ten wskaźnik i sprawdzaj ustawienia serwera, gdy rośnie. Typowe przyczyny:

• Błąd uwierzytelniania: zmieniło się hasło do skrzynki albo dostawca wymaga teraz hasła aplikacji.
• Problemy z połączeniem: host lub port w ustawieniach serwera są błędne.
• Limity dostawcy: dostawca poczty ograniczył dzienną wysyłkę ze skrzynki.
• Odrzucony odbiorca: Twój serwer odrzucił adres podczas wysyłki. Odbicia, które przychodzą później jako e-maile, trafiają do skrzynki nadawczej, a nie do Inbixio, więc sprawdzaj też tę skrzynkę.

Rozwiązanie prawie zawsze znajduje się w Email Servers (serwery pocztowe) albo u Twojego dostawcy poczty. Ustawienia SMTP w praktyce omawiają najczęstsze przypadki.

Co monitorować na produkcji

Panel Inbixio daje Ci to, co najważniejsze:

• Email Sent (wysłane e-maile) i wskaźnik Failed Deliveries z ostatnich 7 dni, każdy ze zmianą względem poprzednich 7 dni.
• Avg Latency (średnie opóźnienie): ile czasu Twój serwer SMTP potrzebuje na przyjęcie poczty. Nagły skok często poprzedza błędy.
• Wykresy wolumenu API i e-maili z całego roku, by wychwycić trendy i sezonowe szczyty.
• Logs (logi) każdego wywołania API: identyfikator zdarzenia, endpoint, metoda, kod statusu, czas odpowiedzi i znacznik czasu.

Po swojej stronie śledź liczbę odpowiedzi innych niż 200 według kodu statusu i ustaw alerty na pojawienie się 401, 402 lub 429 z miesięcznego limitu. Oznaczają one, że cała poczta przestała wychodzić, a Twoi użytkownicy zauważą to szybciej niż Twoje logi.

Checklista

• Traktuj 200 jako „w kolejce”; wyniki dostarczenia sprawdzaj w panelu
• Odczytuj zarówno error, jak i detail z odpowiedzi z błędem
• Ponawiaj tylko błędy sieci, timeouty, 5xx, 503 i 429 z rate limitu, respektując Retry-After
• Ustaw alerty na 401, 402 i 429 z miesięcznego limitu
• Sprawdzaj kartę Usage Limit przed startami i importami
• Obserwuj wskaźnik Failed Deliveries i szybko poprawiaj ustawienia SMTP