Format błędów API i kody błędów

Każda odpowiedź API z błędem ma ten sam format. Twój kod powinien polegać na kodzie błędu w polu error, a nie na tekście w message – kod pozostaje stały, a tekst może się zmienić i jest tłumaczony na język konta.

#Budowa odpowiedzi z błędem

{
  "error": "validation_failed",
  "message": "Some of the information provided is invalid. Please check and try again.",
  "details": [
    { "field": "title", "reason": "minLength", "message": "…" }
  ],
  "request_id": "6b1f0c2e-…"
}

error

Kod czytelny maszynowo, na przykład not_found. Przy większości błędów jest też w nagłówku X-Error-Code – ale polegaj na polu w treści odpowiedzi.

message

Opis czytelny dla człowieka w języku konta: przy kluczu API w języku właściciela workspace, przy połączonej aplikacji w języku osoby, która ją połączyła. Bez ważnego tokenu – na przykład przy 401 z kontroli tokenu – język zależy od Accept-Language, a w przeciwnym razie jest to angielski. Nagłówek Content-Language podaje język.

details

Pojawia się tylko wtedy, gdy jest coś więcej do przekazania. Przy 422 z walidacji danych wejściowych to lista z field, reason i message dla każdego problemu; przy 422 z logiki biznesowej i wszystkich innych błędach to obiekt, na przykład z reason, retry_after_sec lub listą issues. Przy przekroczeniu rozmiaru zawiera field, reason i limit, a przy 413 request_too_large max_bytes i max_kb. Sprawdzaj więc, czy details jest listą.

request_id

ID żądania. Jest też w nagłówku X-Request-Id. Podaj je, gdy kontaktujesz się z pomocą techniczną.

Wyjątki: odpowiedź 429 rate_limited ma pole retry_after_sec zamiast details; przy 429 i 403 insufficient_scope w treści brakuje request_id. 401 z kontroli tokenu i 422 z kontroli schematu nie mają nagłówka X-Error-Code, a przy kontroli schematu tłumaczony jest tylko message najwyższego poziomu; teksty w details pozostają po angielsku. Nagłówek X-Request-Id jest ustawiany zawsze.

#Najważniejsze kody

#Odczytywanie błędów danych wejściowych

Przy 422 validation_failed details wymienia każdy problem osobno: field to ścieżka pola (z ukośnikami dla zagnieżdżonych obiektów, na przykład theme_config/button_style), reason to złamana reguła, taka jak required, minLength, maxLength, enum lub additionalProperties. Przy additionalProperties komunikat mówi, które pola są nieznane – często chodzi o literówkę w nazwie pola.

#Zalecana obsługa w kodzie

• 400, 413 i 422: nie ponawiaj, tylko popraw żądanie
• 401 invalid_token: pobierz raz nowy token i ponów
• 403: nie ponawiaj; sprawdź zakres, plan lub to, kto może wykonać tę akcję
• 404: sprawdź ID; po usunięciu to normalne
• 409: wczytaj stan ponownie i zdecyduj, czy akcja jest nadal potrzebna
• 429: odczekaj tyle, ile podaje Retry-After, a potem ponów – zobacz Limity zapytań
• 500 i 503: ponów kilka razy z rosnącymi przerwami