Kompletna dokumentacja wszystkich kodów błędów w API GraphQL Blue, zorganizowana według kategorii
API GraphQL Blue zwraca błędy w ustandaryzowanym formacie zgodnym ze specyfikacją GraphQL. Gdy wystąpi błąd, odpowiedź zawiera tablicę errors z szczegółowymi informacjami na temat tego, co poszło nie tak.
Przykład odpowiedzi błędu
{
"errors": [
{
"message": "Todo was not found.",
"extensions": {
"code": "TODO_NOT_FOUND"
}
}
]
}
Struktura błędu
Każdy obiekt błędu zawiera:
- message: Opis błędu w formie czytelnej dla człowieka
- extensions.code: Kod błędu w formacie zrozumiałym dla maszyn do obsługi programowej
Bezpieczeństwo błędów produkcyjnych
Blue wdraża system bezpieczeństwa dla ujawniania błędów:
- Bezpieczne błędy: Wyświetlają rzeczywiste kody błędów i komunikaty klientom
- Niebezpieczne błędy: Zwracają ogólny
INTERNAL_SERVER_ERROR, aby ukryć wrażliwe szczegóły
- Nie znaleziono zasobu: Wszystkie błędy
*_NOT_FOUND są uważane za bezpieczne i zawsze ujawniane
Kategorie błędów
Blue definiuje 108 niestandardowych kodów błędów zorganizowanych w następujące kategorie:
Błędy uwierzytelniania i autoryzacji
| Kod błędu |
Komunikat |
Opis |
UNAUTHENTICATED |
"Wymagana autoryzacja." |
Żądanie wymaga autoryzacji, ale nie została podana |
FORBIDDEN |
"Nie jesteś autoryzowany." |
Uwierzytelniony, ale brakuje wymaganych uprawnień |
Błędy "Nie znaleziono zasobu" (łącznie 52)
Zasoby podstawowe
| Kod błędu |
Komunikat |
Opis |
TODO_NOT_FOUND |
"Todo nie zostało znalezione." |
Rekord/todo nie istnieje lub użytkownik nie ma dostępu |
TODO_LIST_NOT_FOUND |
"Lista todo nie została znaleziona." |
Lista nie istnieje lub użytkownik nie ma dostępu |
PROJECT_NOT_FOUND |
"Projekt nie został znaleziony." |
Projekt nie istnieje lub użytkownik nie ma dostępu |
COMPANY_NOT_FOUND |
"Firma nie została znaleziona." |
Firma nie istnieje lub użytkownik nie ma dostępu |
USER_NOT_FOUND |
"Użytkownik nie został znaleziony." |
Użytkownik nie istnieje w systemie |
| Kod błędu |
Komunikat |
Opis |
CUSTOM_FIELD_NOT_FOUND |
"Niestandardowe pole nie zostało znalezione." |
Niestandardowe pole nie istnieje |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"Opcja niestandardowego pola nie została znaleziona." |
Opcja pola wyboru nie istnieje |
FORM_NOT_FOUND |
"Formularz nie został znaleziony." |
Szablon formularza nie istnieje |
FORM_FIELD_NOT_FOUND |
"Pole formularza nie zostało znalezione." |
Pole formularza nie istnieje |
Komponenty projektu
| Kod błędu |
Komunikat |
Opis |
TAG_NOT_FOUND |
"Tag nie został znaleziony." |
Tag nie istnieje w projekcie |
AUTOMATION_NOT_FOUND |
"Automatyzacja nie została znaleziona." |
Reguła automatyzacji nie istnieje |
CHART_NOT_FOUND |
"Wykres nie został znaleziony." |
Wykres na pulpicie nie istnieje |
WEBHOOK_NOT_FOUND |
"Webhook nie został znaleziony." |
Konfiguracja webhooka nie istnieje |
TEMPLATE_NOT_FOUND |
"Szablon nie został znaleziony." |
Szablon projektu nie istnieje |
Komentarze i aktywności
| Kod błędu |
Komunikat |
Opis |
COMMENT_NOT_FOUND |
"Komentarz nie został znaleziony." |
Komentarz nie istnieje |
ACTIVITY_NOT_FOUND |
"Aktywność nie została znaleziona." |
Wpis w dzienniku aktywności nie istnieje |
REACTION_NOT_FOUND |
"Reakcja nie została znaleziona." |
Reakcja na komentarz nie istnieje |
Inne zasoby
| Kod błędu |
Komunikat |
Opis |
FILE_NOT_FOUND |
"Plik nie został znaleziony." |
Załącznik pliku nie istnieje |
SUBSCRIPTION_NOT_FOUND |
"Subskrypcja nie została znaleziona." |
Subskrypcja rozliczeniowa nie istnieje |
INVOICE_NOT_FOUND |
"Faktura nie została znaleziona." |
Rekord faktury nie istnieje |
CHECKLIST_NOT_FOUND |
"Lista kontrolna nie została znaleziona." |
Lista kontrolna nie istnieje |
CHECKLIST_ITEM_NOT_FOUND |
"Element listy kontrolnej nie został znaleziony." |
Element listy kontrolnej nie istnieje |
PROJECT_ROLE_NOT_FOUND |
"Rola projektu nie została znaleziona." |
Niestandardowa rola projektu nie istnieje |
PROJECT_ACCESS_NOT_FOUND |
"Dostęp do projektu nie został znaleziony." |
Dostęp użytkownika do projektu nie istnieje |
NOTIFICATION_NOT_FOUND |
"Powiadomienie nie zostało znalezione." |
Powiadomienie nie istnieje |
DASHBOARD_NOT_FOUND |
"Pulpit nawigacyjny nie został znaleziony." |
Pulpit nawigacyjny nie istnieje |
KEY_NOT_FOUND |
"Klucz nie został znaleziony." |
Klucz ustawień nie istnieje |
Błędy walidacji
| Kod błędu |
Komunikat |
Opis |
BAD_USER_INPUT |
"Nieprawidłowe dane wejściowe." |
Ogólny błąd walidacji danych wejściowych |
VALIDATION_ERROR |
"Nieprawidłowe parametry" |
Parametry żądania nie przeszły walidacji |
BAD_EMAIL |
"Musisz wprowadzić prawidłowy adres e-mail." |
Nieprawidłowy format adresu e-mail |
INVALID_IDS |
"Nieprawidłowe identyfikatory." |
Jeden lub więcej identyfikatorów w żądaniu jest nieprawidłowych |
PHONE_INVALID |
"Numer telefonu jest nieprawidłowy." |
Nieprawidłowy format numeru telefonu |
URL_INVALID |
"URL jest nieprawidłowy." |
Nieprawidłowy format URL |
INVALID_RECURRING_DUE_DATE |
"Nieprawidłowa data wykonania dla zadania cyklicznego" |
Walidacja daty zadania cyklicznego nie powiodła się |
INVALID_COLOR |
"Nieprawidłowy kolor" |
Wartość koloru nie odpowiada oczekiwanemu formatowi |
Błędy logiki biznesowej
Limity i kwoty
| Kod błędu |
Komunikat |
Opis |
COMPANY_LIMIT |
"Osiągnięto limit firm dla twojego konta." |
Osiągnięto maksymalną liczbę firm |
PROJECT_LIMIT |
"Osiągnięto limit projektów dla twojej firmy." |
Osiągnięto maksymalną liczbę projektów |
USER_LIMIT |
"Osiągnięto limit użytkowników dla twojej firmy." |
Osiągnięto maksymalną liczbę użytkowników |
PROJECT_TEMPLATE_LIMIT |
"Osiągnięto limit szablonów dla twojej firmy." |
Osiągnięto maksymalną liczbę szablonów |
CUSTOM_FIELD_LIMIT |
"Osiągnięto limit pól niestandardowych." |
Osiągnięto maksymalną liczbę pól niestandardowych |
TODO_LIST_LIMIT |
"Osiągnięto limit list dla twojego projektu." |
Maksymalna liczba list na projekt |
TOO_MANY_TODOS |
"Zbyt wiele todo." |
Przekroczono limit rekordów |
TOO_MANY_OPTIONS |
"Zbyt wiele opcji." |
Przekroczono limit opcji pola wyboru |
MAX_FILE_SIZE |
"Maksymalny rozmiar pliku to 4,8 GB" |
Przekroczono limit rozmiaru przesyłanego pliku |
Konflikty zasobów
| Kod błędu |
Komunikat |
Opis |
TAG_ALREADY_EXISTS |
"Tag już istnieje." |
Tag o tej samej nazwie istnieje w projekcie |
COMPANY_SLUG_ALREADY_EXISTS |
"Firma już istnieje." |
Slug/URL firmy jest zajęty |
USER_ALREADY_EXISTS |
"Użytkownik już istnieje." |
Adres e-mail użytkownika jest już zarejestrowany |
ALREADY_INVITED |
"Użytkownik jest już zaproszony." |
Użytkownik ma już oczekujące zaproszenie |
USER_ALREADY_IN_PROJECT |
"Użytkownik jest już w tym projekcie." |
Użytkownik ma już dostęp do projektu |
FILE_TYPE_NOT_ALLOWED |
"Typ pliku nie jest dozwolony." |
Typ przesyłanego pliku jest ograniczony |
Błędy uprawnień i dostępu
| Kod błędu |
Komunikat |
Opis |
UNABLE_TO_DELETE_ONLY_ADMIN |
"Nie można usunąć jedynego administratora w firmie." |
Nie można usunąć ostatniego administratora |
UNABLE_TO_UPDATE_OWNER |
"Nie można zaktualizować WŁAŚCICIELA." |
Nie można zmodyfikować uprawnień właściciela |
TODO_LIST_IS_HIDDEN |
"Lista todo jest ukryta." |
Lista ukryta przed rolą użytkownika |
COMPANY_NOT_ACTIVE |
"Firma nie jest aktywna." |
Subskrypcja firmy nieaktywna |
PROJECT_NOT_ACTIVE |
"Projekt nie jest aktywny." |
Projekt jest zarchiwizowany/nieaktywny |
Błędy integralności danych
| Kod błędu |
Komunikat |
Opis |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"Nie można usunąć listy z zadaniami." |
Lista musi być pusta, aby ją usunąć |
UNABLE_TO_DELTE_FILE |
"Nie można usunąć pliku." |
Usunięcie pliku nie powiodło się (błąd w kodzie) |
UNABLE_TO_MOVE_TODO |
"Nie można przenieść todo." |
Nie można przenieść rekordu między listami |
DEPENDENCY_HAS_DEPENDENCY |
"Zależność ma zależność" |
Wykryto cykliczną zależność |
TODO_DEPENDS_ON_ITSELF |
"Todo zależy od siebie" |
Zależność samoreferencyjna |
Błędy Stripe/Płatności
| Kod błędu |
Komunikat |
Opis |
STRIPE_CREATING_CUSTOMER |
"Błąd podczas tworzenia klienta w Stripe." |
Tworzenie klienta Stripe nie powiodło się |
STRIPE_ALREADY_SUBSCRIBED |
"Już subskrybowano." |
Aktywna subskrypcja istnieje |
STRIPE_MISSING_PAYMENT_METHOD |
"Brak metody płatności." |
Brak metody płatności w pliku |
STRIPE_CREATING_SUBSCRIPTION |
"Błąd podczas tworzenia subskrypcji w Stripe." |
Tworzenie subskrypcji nie powiodło się |
STRIPE_UPDATING_SUBSCRIPTION |
"Błąd podczas aktualizacji subskrypcji w Stripe." |
Aktualizacja subskrypcji nie powiodła się |
STRIPE_CHECKOUT_SESSION |
"Błąd podczas tworzenia sesji checkout w Stripe." |
Tworzenie sesji checkout nie powiodło się |
STRIPE_CUSTOMER_PORTAL |
"Błąd podczas tworzenia portalu klienta w Stripe." |
Tworzenie sesji portalu nie powiodło się |
STRIPE_TAX_ID |
"Nie można zapisać identyfikatora podatkowego" |
Walidacja/zapis identyfikatora podatkowego nie powiodła się |
PAYMENT_REQUIRED |
"Wymagana płatność." |
Funkcja wymaga aktywnej subskrypcji |
NO_PAYMENT_REQUIRED |
"Nie wymagana płatność." |
Płatność nie jest potrzebna do operacji |
Błędy uwierzytelniania i sesji
| Kod błędu |
Komunikat |
Opis |
INVALID_CREDENTIALS |
"Nieprawidłowe dane uwierzytelniające." |
Nazwa użytkownika/hasło niepoprawne |
EXPIRED_RESET_TOKEN |
"Token resetowania wygasł." |
Token resetowania hasła wygasł |
OAUTH_FAILED |
"Proces OAuth nie powiódł się." |
Uwierzytelnienie OAuth nie powiodło się |
SAML_NOT_ENABLED |
"SSO (SAML) nie jest włączone." |
SAML SSO nie jest skonfigurowane |
SSO_AUTO_PROVISION_DISABLED |
"Automatyczne tworzenie jest wyłączone." |
Nie można automatycznie tworzyć użytkowników SSO |
Ograniczenia szybkości
Ograniczenia szybkości są obsługiwane przez pakiet graphql-rate-limit z różnymi konfiguracjami:
| Typ limitu |
Okno |
Maks. żądania |
Zastosowane do |
| Standard |
60s |
500 |
Most queries/mutations |
| Sensitive |
300s |
10 |
Password reset, auth operations |
| Expensive |
60s |
20 |
Complex queries, bulk operations |
| Search |
60s |
60 |
Search operations |
| File Upload |
60s |
100 |
File upload operations |
Gdy wystąpi ograniczenie szybkości, otrzymasz standardowy błąd GraphQL z komunikatem wskazującym, że limit został przekroczony.
Błędy systemowe i wewnętrzne
| Kod błędu |
Komunikat |
Opis |
INTERNAL_SERVER_ERROR |
"Wewnętrzny błąd serwera." |
Ogólny błąd dla niebezpiecznych błędów w produkcji |
UNKNOWN_ERROR |
"Nieznany błąd." |
Wystąpił nieoczekiwany błąd |
RESOLVER_NOT_FOUND |
"Resolver nie został znaleziony" |
Brak resolvera GraphQL |
FIELD_NOT_IN_SCHEMA |
"Pole nie znajduje się w schemacie" |
Żądane pole nie istnieje |
Najlepsze praktyki obsługi błędów
Obsługa po stronie klienta
try {
const result = await client.mutate({
mutation: CREATE_TODO,
variables: { input }
});
} catch (error) {
if (error.graphQLErrors?.length > 0) {
const errorCode = error.graphQLErrors[0].extensions?.code;
switch (errorCode) {
case 'UNAUTHENTICATED':
// Redirect to login
break;
case 'TODO_NOT_FOUND':
// Show "Record not found" message
break;
case 'VALIDATION_ERROR':
// Display validation errors
break;
default:
// Show generic error message
}
}
}
Typowe scenariusze błędów
- Wymagana autoryzacja:
UNAUTHENTICATED - Użytkownik musi się zalogować
- Odmowa dostępu:
FORBIDDEN - Użytkownik nie ma wymaganej roli/uprawnienia
- Nie znaleziono zasobu:
*_NOT_FOUND - Zasób nie istnieje lub użytkownik nie ma do niego dostępu
- Walidacja nie powiodła się:
VALIDATION_ERROR, BAD_USER_INPUT - Sprawdź parametry wejściowe
- Ograniczenie szybkości: Sprawdź nagłówki limitu szybkości i wdroż strategię opóźnienia
- Wymagana płatność:
PAYMENT_REQUIRED - Funkcja wymaga subskrypcji
Powiązana dokumentacja