Błędy

SIP Caller używa standardowych kodów statusu HTTP, aby wskazać, czy żądanie się powiodło. Kody z zakresu 2xx oznaczają sukces, kody z zakresu 4xx oznaczają problem z żądaniem (na przykład brak pola lub nieistniejący rekord), a kody z zakresu 5xx oznaczają problem po stronie SIP Caller.

Format odpowiedzi z błędem

Odpowiedzi z błędem mają treść JSON zgodną ze standardem Problem Details:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.4",
  "title": "One or more errors occurred.",
  "status": 404,
  "detail": "Campaign with id '01a0dedd-b9a2-729d-8e0a-4e3ad9197aea' not found",
  "instance": "/v1/accounts/ACCOUNT_ID/campaigns/01a0dedd-b9a2-729d-8e0a-4e3ad9197aea",
  "traceId": "0HN6QKQ1B2F3G:00000001"
}

Pole	Opis
type	URL identyfikujący typ błędu, oparty na kodzie statusu HTTP.
title	Krótkie, ogólne podsumowanie błędu.
status	Kod statusu HTTP.
detail	Czytelne dla człowieka wyjaśnienie tego konkretnego błędu. Nie występuje w błędach walidacji.
instance	Ścieżka żądania, które spowodowało błąd.
traceId	Unikalny identyfikator żądania. Podaj go, kontaktując się z pomocą techniczną w sprawie błędu.
errors	Tylko w błędach 400 i 409: lista komunikatów dla każdego nieprawidłowego pola, zgodnie z opisem poniżej.

Komunikaty detail i errors mają pomóc programistom zrozumieć problem. Nie analizuj ich w swoim kodzie, ponieważ ich treść może się zmienić: zamiast tego używaj kodu statusu HTTP.

Błędy walidacji

Gdy jedno lub więcej pól żądania jest nieprawidłowych, API zwraca błąd 400 Bad Request z obiektem errors. Każdy klucz to nazwa nieprawidłowego pola (z kropkami dla pól zagnieżdżonych), a każda wartość to lista znalezionych problemów:

{
  "type": "https://tools.ietf.org/html/rfc7231#section-6.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "instance": "/v1/accounts/ACCOUNT_ID/campaigns",
  "errors": {
    "name": ["Value must not be empty."],
    "maxAttempts": ["Value must be between 1 and 9."]
  },
  "traceId": "0HN6QKQ1B2F3G:00000002"
}

Wszystkie nieprawidłowe pola są zgłaszane jednocześnie, dzięki czemu możesz je poprawić w jednym kroku. Błędy w parametrach zapytania filter, sort i range są zgłaszane w ten sam sposób, pod tymi kluczami.

Kody statusu HTTP

Kod	Znaczenie
200 OK	Żądanie się powiodło.
201 Created	Zasób został utworzony. Odpowiedź zawiera nowy zasób.
400 Bad Request	Żądanie jest nieprawidłowe: brakuje wymaganego pola, wartość ma nieprawidłowy format lub jest spoza zakresu albo JSON jest źle sformatowany. Zobacz pole errors lub detail.
401 Unauthorized	Nie podano prawidłowego klucza API. Zobacz Uwierzytelnianie.
403 Forbidden	Klucz API nie ma uprawnień do wykonania operacji.
404 Not Found	Zasób nie istnieje lub nie należy do konta.
408 Request Timeout	Treść żądania była wysyłana zbyt wolno.
409 Conflict	Żądanie jest sprzeczne z bieżącym stanem zasobu. Na przykład nazwa, która musi być unikalna, jest już używana, lub zasobu nie można usunąć, ponieważ jest używany.
412 Precondition Failed	Zasób został zmodyfikowany przez kogoś innego od czasu, gdy ostatnio go odczytałeś. Zobacz Równoczesne aktualizacje poniżej.
413 Payload Too Large	Treść żądania przekracza maksymalny rozmiar 20 MB.
429 Too Many Requests	W krótkim czasie wysłano zbyt wiele żądań. Zobacz Limity żądań.
500 Internal Server Error	Coś poszło nie tak po stronie SIP Caller. Nasz zespół jest powiadamiany automatycznie. Możesz ponowić żądanie później.

Równoczesne aktualizacje

Aby zapobiec utracie zmian, gdy ten sam zasób jest edytowany jednocześnie przez różnych użytkowników lub aplikacje, żądania aktualizacji (na przykład Aktualizacja kampanii) wymagają pola lastUpdatedAt. Musi ono zawierać wartość updatedAt zasobu, zwróconą przy ostatnim jego pobraniu, utworzeniu lub edycji.

Jeśli w międzyczasie zasób został zmodyfikowany, jego wartość updatedAt już się nie zgadza, a aktualizacja jest odrzucana z błędem 412 Precondition Failed:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.13",
  "title": "One or more errors occurred.",
  "status": 412,
  "detail": "Update aborted to prevent 'lost update' problem; retry with correct 'lastUpdatedAt' value",
  "instance": "/v1/accounts/ACCOUNT_ID/blackLists/BLACK_LIST_ID",
  "traceId": "0HN6QKQ1B2F3G:00000003"
}

Gdy otrzymasz ten błąd, pobierz zasób ponownie, zastosuj swoje zmiany do najnowszej wersji i wyślij aktualizację z nową wartością lastUpdatedAt.

Obsługa błędów

W swojej integracji zalecamy następujące podejście:

• Błędy 4xx (z wyjątkiem 429): nie ponawiaj tego samego żądania, ponieważ ponownie zakończy się błędem. Zapisz odpowiedź w logach, wraz z traceId, i popraw żądanie.
• Błędy 429: odczekaj liczbę sekund wskazaną w nagłówku Retry-After i ponów żądanie.
• Błędy 5xx i błędy sieci: ponawiaj z wykładniczym opóźnieniem (na przykład po 1, 2, 4 i 8 sekundach). Zachowaj ostrożność przy ponawianiu żądań, które tworzą zasoby lub dodają numery, ponieważ pierwsza próba mogła się powieść przed wystąpieniem błędu: przed ponowieniem sprawdź bieżący stan.