Obsługa błędów
API wykorzystuje konwencjonalne kody odpowiedzi HTTP do wskazania sukcesu lub niepowodzenia żądań. Ta strona dokumentuje formaty błędów i strategie ich obsługi.
Formaty odpowiedzi o błędach
Format zależy od tego, gdzie generowany jest błąd.
Błędy uwierzytelniania i limitu żądań (401 i 429)
Niewielki obiekt JSON z polami error, message i status. Wyjątkiem są punkty końcowe zmian zasad, punkt końcowy kodu QR do aprowizacji oraz punkty końcowe poleceń urządzeń inne niż lock, lost-mode, found i message: ich błąd 429 używa poniższego formatu problem details z polami code i retryable.
HTTP/1.1 429 Too Many Requests
Retry-After: 30
Content-Type: application/json
{
"error": "Too Many Requests",
"message": "Rate limit exceeded for device commands on this API key. Try again later.",
"status": 429
} Wszystkie inne błędy (na przykład 400, 403, 409, 422, 500, 502 i 503)
RFC 9457 problem details z typem zawartości application/problem+json. Błędy walidacji dodają tablicę errors. Punkty końcowe zmian zasad, punkt końcowy kodu QR do aprowizacji oraz punkty końcowe poleceń urządzeń inne niż lock, lost-mode, found i message dodają pole code do każdego błędu z wyjątkiem 401. W punkcie końcowym kodu QR do aprowizacji treść, która nie jest poprawnym formatem JSON lub zawiera nieznane pole, również stanowi wyjątek: jej błąd 400 nie zawiera pola code. Pole retryable zostało opisane poniżej.
HTTP/1.1 400 Bad Request
Content-Type: application/problem+json
{
"type": "VALIDATION_ERROR",
"title": "Validation Error",
"status": 400,
"instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
"errors": [
{ "field": "title", "index": null, "message": "must not be blank" }
]
} | Pole | Opis |
|---|---|
| type | Typ błędu lub about:blank |
| title | Krótkie podsumowanie, takie jak fraza statusu HTTP |
| status | Kod statusu HTTP |
| detail | Zrozumiałe dla człowieka wyjaśnienie tego błędu |
| instance | Ścieżka żądania |
| errors | Błędy walidacji na poziomie pól, każdy z polami field, index i message (tylko 400) |
| code | Stabilny kod błędu do obsługi warunkowej, taki jak not_found, forbidden lub internal_error. Wysyłany przez punkty końcowe zmian zasad, punkt końcowy kodu QR do wdrażania oraz punkty końcowe poleceń urządzeń inne niż lock, lost-mode, found i message. |
| retryable | true, jeśli to samo żądanie może zostać ponowione. Wysyłane przy 502 i 503 z każdego punktu końcowego poleceń urządzeń, przy 429 i 500 z punktów końcowych poleceń innych niż lock, lost-mode, found i message, a także przy każdym błędzie zawierającym code z punktów końcowych zmian zasad i punktu końcowego kodu QR do aprowizacji. |
Błąd 404 dla nieznanego zasobu lub zasady ma pustą treść. Wyjątkiem są punkty końcowe zmian zasad, punkt końcowy kodu QR do aprowizacji oraz punkty końcowe poleceń urządzeń inne niż lock, lost-mode, found i message: ich błąd 404 to problem details z polem code o wartości not_found.
Punkty końcowe sesji użytkownika urządzenia zwracają błędy 400, 404 i 409 w formacie application/problem+json z polem code służącym do obsługi warunkowej; nie przesyłają pola retryable. Dwa wyjątki nie posiadają kodu: 401 i 403, a także błąd 400 dla nieprawidłowego parametru zapytania w GET /device-user-logins. API sesji użytkowników urządzeń
Kody statusu HTTP
| Kod | Opis |
|---|---|
| 400 | Nieprawidłowe parametry żądania lub błędnie skonstruowane ciało żądania |
| 401 | Brakujący lub nieprawidłowy klucz API |
| 403 | Klucz API nie ma wymaganych uprawnień dla tego punktu końcowego |
| 404 | Żądany zasób nie istnieje |
| 429 | Przekroczono limit żądań - spróbuj ponownie po określonym czasie |
| 500 | Wewnętrzny błąd serwera - skontaktuj się z pomocą techniczną, jeśli problem będzie się utrzymywał |
| 503 | Usługa tymczasowo niedostępna - spróbuj ponownie później |
Odpowiedzi na polecenia urządzenia
Punkty końcowe poleceń używają kodów stanu ze specjalnymi regułami ponawiania prób. Ponowienie nieodpowiedniego polecenia może spowodować dostarczenie go do urządzenia dwukrotnie.
| 202 | Wynik nieznany. Nie wysyłaj ponownie. Najpierw sprawdź historię poleceń. |
|---|---|
| 500 | Nieoczekiwany błąd z kodem internal_error poza punktami końcowymi lock, lost-mode, found i message. To, czy polecenie dotarło do urządzenia, jest nieznane. Przed ponowieniem próby sprawdź urządzenie. |
| 503 | Nie wysłano. Można bezpiecznie ponowić próbę. |
| 502 | Dostawca odrzucił polecenie. Ponów próbę tylko wtedy, gdy retryable ma wartość true. |
| 409 | Urządzenie nie może przyjąć tego polecenia. Ponawianie prób nie powiedzie się, dopóki jego stan nie ulegnie zmianie. |
| 422 | Dostawca odrzucił polecenie. Nie ponawiaj próby z tymi samymi argumentami. |
HTTP/1.1 202 Accepted
{
"assetId": "k3x9m2pa",
"type": "LOCK",
"status": "UNCONFIRMED",
"detail": "The command's outcome is unknown. Check the device's command history (list_device_commands or GET /api/v1/assets/{assetId}/commands) before retrying; it may only appear once the device acknowledges it."
} HTTP/1.1 503 Service Unavailable
Content-Type: application/problem+json
{
"type": "about:blank",
"title": "Service Unavailable",
"status": 503,
"detail": "Command was not sent; it is safe to retry.",
"instance": "/emm/api/v1/assets/k3x9m2pa/commands/message",
"retryable": true
} Strategia ponawiania prób
Ponawiaj próby tylko wtedy, gdy jest to bezpieczne. Żądania odczytu zakończone błędem przejściowym można ponawiać z wykorzystaniem wykładniczego wycofywania (exponential backoff). Komenda urządzenia musi być zgodna z zasadami opisanymi w sekcji odpowiedzi komend urządzeń. Po błędzie zmiany zasad lub kodu QR do aprowizacji należy postępować zgodnie z polem retryable, a po nieoczekiwanym błędzie podczas operacji apply należy odczytać wniosek (proposal) przed ponownym złożeniem wniosku.
- W przypadku błędów 429 przed ponowieniem próby odczekaj liczbę sekund wskazaną w nagłówku Retry-After.
- W przypadku błędów 5xx przy żądaniach odczytu stosuj wykładnicze wycofywanie (1s, 2s, 4s, 8s...) z losowym rozrzutem (jitter). W przypadku komend urządzeń ponawiaj wyłącznie błąd 503 (niewysłano) lub 502 z polem retryable ustawionym na true. Po otrzymaniu kodu 202 lub 500 sprawdź stan urządzenia przed ponownym wysłaniem.
- Ustaw maksymalną liczbę ponawianych prób (np. 3-5 prób), aby uniknąć pętli nieskończonych
Ograniczanie częstotliwości żądań
W przypadku przekroczenia limitu żądań MCP lub wywołania punktu końcowego lock, lost-mode, found lub message powyżej limitu poleceń, interfejs API zwraca błąd HTTP 429 Too Many Requests z nagłówkiem Retry-After i treścią JSON zawierającą error, message i status. Pozostałe punkty końcowe poleceń urządzeń, punkty końcowe zmian zasad oraz punkt końcowy kodu QR do aprowizacji również wysyłają Retry-After po przekroczeniu tego samego limitu, ale ich treścią jest problem details z wartością code równą rate_limited i wartością retryable równą true. Gdy wywołanie polecenia MCP, zmiany zasad lub narzędzia aprowizacji przekroczy limit poleceń, wynikiem jest błąd narzędzia, którego tekst informuje, ile sekund należy odczekać.
Użyj nagłówka Retry-After lub liczby sekund podanej w błędzie narzędzia, aby zdecydować, kiedy ponowić próbę. Interfejs API nie wysyła nagłówków X-RateLimit-Limit, X-RateLimit-Remaining ani X-RateLimit-Reset.
Błędy walidacji
W przypadku błędów 400 spowodowanych nieprawidłową treścią żądania obiekt problem details zawiera tablicę errors z jednym wpisem dla każdego nieprawidłowego pola. Inne błędy 400, takie jak nieprawidłowa wartość lastSeenBefore, szczegółowo wyjaśniają problem.
Najlepsze praktyki obsługi błędów
- Zawsze sprawdzaj kod statusu HTTP przed parsowaniem treści odpowiedzi
- Stosuj się do nagłówka Retry-After przy błędzie 429 i używaj wykładniczego wycofywania przy błędach 5xx dla żądań odczytu. W przypadku komend urządzeń ponawiaj wyłącznie błąd 503 lub 502 z wartością retryable ustawioną na true i nigdy nie wysyłaj ich ponownie po kodzie 202 lub 500 bez uprzedniego sprawdzenia urządzenia.
- Rejestruj status HTTP oraz szczegóły (detail) lub komunikat (message) z treści błędu w celach diagnostycznych. Treści błędów nie zawierają pól timestamp ani path.
- Obsłuż konkretne kody błędów inaczej (np. 401 wyzwala ponowne uwierzytelnienie)