Kod błędu 500 przy wysyłaniu SMS przez API

Błąd 500 (Internal Server Error) podczas wysyłania SMS przez API oznacza, że serwer napotkał problem przy obsłudze żądania. Nie mówi jeszcze, co dokładnie się stało.^1,2 Źródła błędu szukaj w odpowiedzi i logach, a przed ponowieniem wywołania sprawdź status wiadomości.
Zgodnie z RFC 9110 §15.6.1 kod 500 oznacza nieoczekiwany stan serwera, który uniemożliwił obsługę żądania³.

Czym jest kod błędu 500 przy wysyłaniu SMS przez API?

Kod błędu 500 to odpowiedź HTTP z kategorii 5xx, wskazującej problem po stronie serwera. Dotyczy wywołania SMS API, przez które aplikacja zleca wysyłkę wiadomości. Nie jest raportem doręczenia SMS do telefonu. Kody błędów serwera HTTP mieszczą się w zakresie 500–599³.

Odpowiedź HTTP informuje aplikację o wyniku żądania skierowanego do serwera. Raport doręczeń opisuje późniejszy los wiadomości u odbiorcy.
Sam kod odpowiedzi nie zastępuje raportu. Nie przesądza też, czy serwer przyjął zlecenie przed wystąpieniem błędu. Kod 201 oznacza utworzenie zasobu, na przykład zlecenia wysyłki, a nie doręczenie SMS³.

Co oznacza HTTP 500 i czym różni się od błędu dostarczenia SMS?

HTTP 500 dotyczy obsługi żądania przez serwer; błąd dostarczenia dotyczy wiadomości objętej procesem wysyłki. Aplikacja otrzymuje odpowiedź HTTP po wywołaniu API. Status doręczenia odczytuje osobno, z raportu lub innego mechanizmu danej usługi.
Błąd API nie potwierdza więc niedoręczenia. Kod 202 oznacza przyjęcie żądania do przetworzenia, ale także nie potwierdza doręczenia SMS³.

Tabela rozdziela odpowiedź HTTP i raport doręczeń według etapu, którego dotyczą.

Dane w tabeli: 3

Przy diagnozie sprawdzaj osobno wynik wywołania API i los wiadomości. To dwa różne etapy.

Jak ponowić żądanie po błędzie 500, aby nie wysłać duplikatu SMS?

Po błędzie 500 nie ponawiaj żądania, dopóki nie ustalisz, czy poprzednie wywołanie utworzyło zlecenie wysyłki. Bez tej kontroli możesz wysłać ten sam SMS ponownie. RFC 9110 §9.2.2 nie zalicza POST do metod idempotentnych. Automatyczne ponowienie zlecenia może więc utworzyć duplikat³.

Przed ponowieniem wywołania wykonaj następujące czynności:

• Identyfikator żądania zachowaj razem z odpowiedzią API i danymi wysyłki. Dzięki temu odnajdziesz pierwotne wywołanie.
• Status zlecenia odczytaj przez mechanizm udostępniany przez usługę SMS. Jeśli zlecenie już istnieje, nie twórz go ponownie.
• Klucz idempotencji zachowaj przy ponowieniu, jeśli używane API go obsługuje. Usługa może wtedy rozpoznać wywołanie dotyczące tej samej operacji.
• Ponowną wysyłkę uruchom po wykluczeniu wcześniejszego zlecenia albo zgodnie z zasadami ponawiania dla używanego API.

Sprawdzenie istniejącego zlecenia ogranicza ryzyko duplikatu. W usłudze Twilio możesz odczytać wiadomość przez API, używając jej 34-znakowego identyfikatora MessageSid⁴.

Czym różnią się przyczyny i sposoby usuwania błędów 500 oraz 503?

Błędy 500 i 503 dotyczą odpowiedzi serwera, lecz wymagają innej pierwszej reakcji. Żaden z tych kodów sam nie wskazuje, czy zawiodła aplikacja wysyłająca SMS, jej serwer czy usługa SMS API.
RFC 9110 §15.6.4 wiąże kod 503 z tymczasową niedostępnością usługi. Dopuszcza też nagłówek Retry-After, który wskazuje czas oczekiwania przed ponowieniem³.

Tabela wskazuje pierwszą czynność dla każdego kodu oraz warunek ponowienia wysyłki.

Dane w tabeli: 3

Nagłówek Retry-After może podawać termin ponowienia jako datę HTTP lub liczbę sekund oczekiwania³.

Możliwe przyczyny błędu 500 w SMS API

Błąd 500 w SMS API może wynikać z usterki kodu, problemu z zależną usługą lub nieobsłużonego wyjątku. Jeśli w wysyłce pośredniczy Twoja aplikacja, sprawdź również jej kod. Nie zakładaj od razu awarii dostawcy SMS. Kod 502 oznacza nieprawidłową odpowiedź, którą brama lub serwer proxy otrzymały od innego serwera. Kod 500 opisuje ogólny błąd serwera³.

PHP może przerwać działanie, jeśli obsługująca integrację aplikacja napotka błąd. Operację mogą też zatrzymać nieprawidłowe uprawnienia do pliku, brak pamięci RAM lub miejsca na serwerze.
Problem z bazą danych może z kolei uniemożliwić odczyt danych potrzebnych do utworzenia zlecenia. Każdą podejrzewaną przyczynę powiąż z wpisem w logach; sam kod jej nie potwierdza. Według dokumentacji PHP domyślna wartość memory_limit wynosi 128M. Przekroczenie ustawionego limitu może przerwać pracę skryptu⁵.

Jak zdiagnozować i naprawić błąd 500?

Diagnozę błędu 500 zacznij od ustalenia, który serwer zwrócił odpowiedź: Twojej aplikacji czy usługi SMS API. Potem zestaw nieudane wywołanie z logami właściwego systemu. Naprawę oprzyj na znalezionej przyczynie.
W powiązaniu wywołania z logami może pomóc 32-znakowy szesnastkowy trace-id. Występuje on w nagłówku traceparent standardu W3C Trace Context⁶.

Lista prowadzi od ustalenia miejsca błędu do sprawdzenia naprawy:

• Adres wywołania i odpowiedź HTTP pomogą ustalić, który serwer obsługiwał żądanie. Rozdziel odpowiedź własnej aplikacji od odpowiedzi usługi SMS API.
• Logi aplikacji i serwera mogą ujawnić wyjątek lub przerwaną operację. Dopasuj wpis do żądania według czasu i identyfikatora.
• Ustalona przyczyna wyznacza sposób naprawy. Popraw kod, uprawnienia lub działanie zależnej usługi zgodnie z komunikatem w logach⁷.
• Weryfikacja naprawy obejmuje nowe żądanie i kontrolę jego statusu. Nie zastępuj diagnozy ponowną wysyłką.

Naprawa jest potwierdzona, gdy nowe żądanie przechodzi bez błędu, a jego wynik można ustalić.

Jak ograniczyć nawroty błędu 500 po naprawie?

Aby ograniczyć nawroty błędu 500, monitoruj miejsce awarii i zabezpiecz operację, która ją wywołała. W integracji SMS API kontrola obejmuje aplikację, zależności serwera oraz wyniki zleceń wysyłki.

Lista obejmuje zabezpieczenia wynikające z diagnozy:

• Obsługa wyjątków powinna zapisywać przyczynę błędu w logach. Odpowiedź API nie powinna przy tym ujawniać danych odbiorcy.
• Monitoring zasobów i zależności powinien wychwytywać problemy z pamięcią, miejscem na serwerze i połączeniem z bazą danych.
• Test po zmianie powinien obejmować wywołanie endpointu API oraz odczyt wyniku zlecenia SMS.

Stałe logowanie i test naprawionej ścieżki pomagają wykryć nawrót błędu, zanim dotknie kolejnych wysyłek.

Czym jest błąd 503 w SMS API?

Błąd 503 w SMS API oznacza, że serwer chwilowo nie może obsłużyć żądania. Przyczyną może być przeciążenie lub prace serwisowe. Kod opisuje dostępność usługi w chwili wywołania, nie doręczenie wiadomości.

Serwer może zwrócić nagłówek Retry-After określający, kiedy ponowić żądanie. Jeśli go zwrócił, aplikacja powinna uwzględnić wskazany czas zamiast wysyłać kolejne żądania bez odstępu.
Najpierw ustal, czy usługa przyjęła poprzednie zlecenie. Błąd 503 sygnalizuje niedostępność obsługi żądania, ale nie dowodzi, że SMS nie został wysłany.

Jak ustalić źródło błędu 500 SMS API na podstawie odpowiedzi, logów i identyfikatora żądania?

Źródła błędu 500 SMS API szukaj w odpowiedzi HTTP oraz logach serwera i aplikacji. Powiąż je identyfikatorem żądania, jeśli go nadano. Wpisy mogą wskazać etap, na którym przerwano obsługę wywołania.^2,8

Lista wskazuje, co zachować z odpowiedzi i gdzie szukać wpisów:

• Odpowiedź HTTP zachowaj z czasem wywołania, adresem endpointu i nagłówkami. Zapisz też identyfikator żądania, jeśli występuje.
• Access Log to dziennik żądań serwera. Przeszukaj go według czasu i adresu endpointu, aby ustalić, czy żądanie dotarło do serwera zwracającego błąd.
• Error Log to dziennik błędów serwera. Znajdź wpis dotyczący żądania, a następnie odczytaj komunikat i miejsce przerwania obsługi.
• Log aplikacji powiąż z wywołaniem przez identyfikator żądania lub czas. Sprawdź, czy wyjątek wystąpił przed kontaktem z usługą SMS, czy po otrzymaniu jej odpowiedzi.

Zestawienie odpowiedzi z wpisami wskazuje miejsce awarii. Nie trzeba przy tym z góry przypisywać jej dostawcy SMS.

Czy błąd 500 SMS API oznacza, że wiadomość nie została wysłana?

Błąd 500 SMS API nie oznacza, że wiadomość nie została wysłana. Usługa mogła przyjąć zlecenie przed wystąpieniem błędu, ale mogła też go nie przyjąć. Sama odpowiedź nie rozstrzyga, który scenariusz wystąpił.

Tabela zestawia możliwe wyniki żądania z potwierdzeniem przyjęcia, statusem SMS i decyzją o ponowieniu wysyłki.

Przyjęcie zlecenia nie oznacza doręczenia SMS odbiorcy. O wyniku wysyłki mówi status wiadomości. Bezpieczne ponowienie zależy natomiast od ustalenia, czy wcześniejsze zlecenie już istnieje.

Werdykt: sam błąd 500 nie uzasadnia ponownej wysyłki SMS.