Omfattande referens för alla felkoder i Blue GraphQL API, organiserade efter kategori
Blue's GraphQL API returnerar fel i ett standardiserat format enligt GraphQL-specifikationen. När ett fel inträffar inkluderar svaret en errors-array med detaljerad information om vad som gick fel.
Exempel på felrespons
{
"errors": [
{
"message": "Todo was not found.",
"extensions": {
"code": "TODO_NOT_FOUND"
}
}
]
}
Felstruktur
Varje felobjekt innehåller:
- meddelande: En människoläsbar beskrivning av felet
- extensions.code: En maskinläsbar felkod för programmeringshantering
Produktionsfelssäkerhet
Blue implementerar ett säkerhetssystem för felexponering:
- Säkra fel: Visa faktiska felkoder och meddelanden till klienter
- Icke-säkra fel: Returnera generiska
INTERNAL_SERVER_ERROR för att dölja känsliga detaljer
- Resurs hittades inte: Alla
*_NOT_FOUND-fel anses vara säkra och exponeras alltid
Felkategorier
Blue definierar 108 anpassade felkoder organiserade i följande kategorier:
Autentisering och auktoriseringsfel
| Felkod |
Meddelande |
Beskrivning |
UNAUTHENTICATED |
"Autentisering krävs." |
Begäran kräver autentisering men ingen tillhandahålls |
FORBIDDEN |
"Du är inte auktoriserad." |
Autentiserad men saknar nödvändiga behörigheter |
Resurs hittades inte-fel (52 totalt)
Kärnresurser
| Felkod |
Meddelande |
Beskrivning |
TODO_NOT_FOUND |
"Todo hittades inte." |
Post/todo existerar inte eller användaren saknar åtkomst |
TODO_LIST_NOT_FOUND |
"Todo-lista hittades inte." |
Lista existerar inte eller användaren saknar åtkomst |
PROJECT_NOT_FOUND |
"Projekt hittades inte." |
Projekt existerar inte eller användaren saknar åtkomst |
COMPANY_NOT_FOUND |
"Företag hittades inte." |
Företag existerar inte eller användaren saknar åtkomst |
USER_NOT_FOUND |
"Användare hittades inte." |
Användaren existerar inte i systemet |
| Felkod |
Meddelande |
Beskrivning |
CUSTOM_FIELD_NOT_FOUND |
"Anpassat fält hittades inte." |
Anpassat fält existerar inte |
CUSTOM_FIELD_OPTION_NOT_FOUND |
"Anpassad fältalternativ hittades inte." |
Valt fältalternativ existerar inte |
FORM_NOT_FOUND |
"Formulär hittades inte." |
Formulärmall existerar inte |
FORM_FIELD_NOT_FOUND |
"Formulärfält hittades inte." |
Formulärfält existerar inte |
Projektkomponenter
| Felkod |
Meddelande |
Beskrivning |
TAG_NOT_FOUND |
"Tagg hittades inte." |
Tagg existerar inte i projektet |
AUTOMATION_NOT_FOUND |
"Automatisering hittades inte." |
Automatiseringsregel existerar inte |
CHART_NOT_FOUND |
"Diagram hittades inte." |
Dashboard-diagram existerar inte |
WEBHOOK_NOT_FOUND |
"Webhook hittades inte." |
Webhook-konfiguration existerar inte |
TEMPLATE_NOT_FOUND |
"Mall hittades inte." |
Projektmall existerar inte |
Kommentarer och aktiviteter
| Felkod |
Meddelande |
Beskrivning |
COMMENT_NOT_FOUND |
"Kommentar hittades inte." |
Kommentar existerar inte |
ACTIVITY_NOT_FOUND |
"Aktivitet hittades inte." |
Aktivitetsloggpost existerar inte |
REACTION_NOT_FOUND |
"Reaktion hittades inte." |
Kommentarreaktion existerar inte |
Andra resurser
| Felkod |
Meddelande |
Beskrivning |
FILE_NOT_FOUND |
"Fil hittades inte." |
Filbilaga existerar inte |
SUBSCRIPTION_NOT_FOUND |
"Prenumeration hittades inte." |
Faktureringsprenumeration existerar inte |
INVOICE_NOT_FOUND |
"Faktura hittades inte." |
Fakturapost existerar inte |
CHECKLIST_NOT_FOUND |
"Checklista hittades inte." |
Checklista existerar inte |
CHECKLIST_ITEM_NOT_FOUND |
"Checklistapunkt hittades inte." |
Checklistapunkt existerar inte |
PROJECT_ROLE_NOT_FOUND |
"Projektroll hittades inte." |
Anpassad projektroll existerar inte |
PROJECT_ACCESS_NOT_FOUND |
"Projektåtkomst hittades inte." |
Användarens projektåtkomst existerar inte |
NOTIFICATION_NOT_FOUND |
"Notifikation hittades inte." |
Notifikation existerar inte |
DASHBOARD_NOT_FOUND |
"Dashboard hittades inte." |
Dashboard existerar inte |
KEY_NOT_FOUND |
"Nyckel hittades inte." |
Inställningsnyckel existerar inte |
Valideringsfel
| Felkod |
Meddelande |
Beskrivning |
BAD_USER_INPUT |
"Ogiltig inmatning." |
Generisk inmatningsvalideringsfel |
VALIDATION_ERROR |
"Ogiltiga parametrar" |
Begärningsparametrar misslyckades med validering |
BAD_EMAIL |
"Du måste ange en giltig e-postadress." |
Ogiltigt e-postformat |
INVALID_IDS |
"Ogiltiga id." |
En eller flera ID:n i begäran är ogiltiga |
PHONE_INVALID |
"Telefon är ogiltig." |
Ogiltigt telefonnummerformat |
URL_INVALID |
"URL är ogiltig." |
Ogiltigt URL-format |
INVALID_RECURRING_DUE_DATE |
"Ogiltigt förfallodatum för återkommande uppgift" |
Validering av datum för återkommande uppgift misslyckades |
INVALID_COLOR |
"Ogiltig färg" |
Färgvärde matchar inte förväntat format |
Affärslogikfel
Gränser och kvoter
| Felkod |
Meddelande |
Beskrivning |
COMPANY_LIMIT |
"Du har nått företagsgränsen för ditt konto." |
Maximalt antal företag nått |
PROJECT_LIMIT |
"Du har nått projektgränsen för ditt företag." |
Maximalt antal projekt nått |
USER_LIMIT |
"Du har nått användargränsen för ditt företag." |
Maximalt antal användare nått |
PROJECT_TEMPLATE_LIMIT |
"Du har nått mallgränsen för ditt företag." |
Maximalt antal mallar nått |
CUSTOM_FIELD_LIMIT |
"Gränsen för anpassade fält nådd." |
Maximalt antal anpassade fält nått |
TODO_LIST_LIMIT |
"Du har nått listgränsen för ditt projekt." |
Maximalt antal listor per projekt |
TOO_MANY_TODOS |
"För många todos." |
Postgräns överskriden |
TOO_MANY_OPTIONS |
"För många alternativ." |
Gräns för valfältalternativ överskriden |
MAX_FILE_SIZE |
"Max filstorlek är 4.8 GB" |
Gräns för filuppladdning överskriden |
Resurskonflikter
| Felkod |
Meddelande |
Beskrivning |
TAG_ALREADY_EXISTS |
"Tagg existerar redan." |
Tagg med samma namn existerar i projektet |
COMPANY_SLUG_ALREADY_EXISTS |
"Företag existerar redan." |
Företagsslag/URL är upptagen |
USER_ALREADY_EXISTS |
"Användare existerar redan." |
Användarens e-postadress är redan registrerad |
ALREADY_INVITED |
"Användaren är redan inbjuden." |
Användaren har redan en väntande inbjudan |
USER_ALREADY_IN_PROJECT |
"Användaren är redan på detta projekt." |
Användaren har redan projektåtkomst |
FILE_TYPE_NOT_ALLOWED |
"Filtyp inte tillåten." |
Uppladdad filtyp är begränsad |
Behörighets- och åtkomstfel
| Felkod |
Meddelande |
Beskrivning |
UNABLE_TO_DELETE_ONLY_ADMIN |
"Kan inte ta bort den enda administratören i företaget." |
Kan inte ta bort sista administratören |
UNABLE_TO_UPDATE_OWNER |
"Kan inte uppdatera ÄGARE." |
Kan inte ändra ägarens behörigheter |
TODO_LIST_IS_HIDDEN |
"Todo-lista är dold." |
Lista dold från användarens roll |
COMPANY_NOT_ACTIVE |
"Företaget är inte aktivt." |
Företagets prenumeration inaktiv |
PROJECT_NOT_ACTIVE |
"Projektet är inte aktivt." |
Projektet är arkiverat/inaktivt |
Dataintegritetsfel
| Felkod |
Meddelande |
Beskrivning |
UNABLE_TO_DELETE_LIST_WITH_TODOS |
"Kan inte ta bort lista med todos." |
Listan måste vara tom för att ta bort |
UNABLE_TO_DELTE_FILE |
"Kan inte ta bort fil." |
Filborttagning misslyckades (stavfel i kod) |
UNABLE_TO_MOVE_TODO |
"Kan inte flytta todo." |
Kan inte flytta post mellan listor |
DEPENDENCY_HAS_DEPENDENCY |
"Beroende har beroende" |
Cirkulärt beroende upptäcktes |
TODO_DEPENDS_ON_ITSELF |
"Todo beror på sig själv" |
Självrefererande beroende |
Stripe/Betalningsfel
| Felkod |
Meddelande |
Beskrivning |
STRIPE_CREATING_CUSTOMER |
"Fel vid skapande av kund i Stripe." |
Skapande av Stripe-kund misslyckades |
STRIPE_ALREADY_SUBSCRIBED |
"Redan prenumererad." |
Aktiv prenumeration existerar |
STRIPE_MISSING_PAYMENT_METHOD |
"Saknar betalningsmetod." |
Ingen betalningsmetod registrerad |
STRIPE_CREATING_SUBSCRIPTION |
"Fel vid skapande av prenumeration i Stripe." |
Skapande av prenumeration misslyckades |
STRIPE_UPDATING_SUBSCRIPTION |
"Fel vid uppdatering av prenumeration i Stripe." |
Uppdatering av prenumeration misslyckades |
STRIPE_CHECKOUT_SESSION |
"Fel vid skapande av kassa-session i Stripe." |
Skapande av kassa-session misslyckades |
STRIPE_CUSTOMER_PORTAL |
"Fel vid skapande av kundportal i Stripe." |
Skapande av portal-session misslyckades |
STRIPE_TAX_ID |
"Kan inte spara skatte-ID" |
Validering/spara av skatte-ID misslyckades |
PAYMENT_REQUIRED |
"Betalning krävs." |
Funktion kräver aktiv prenumeration |
NO_PAYMENT_REQUIRED |
"Ingen betalning krävs." |
Betalning behövs inte för operation |
Autentisering och sessionsfel
| Felkod |
Meddelande |
Beskrivning |
INVALID_CREDENTIALS |
"Ogiltiga uppgifter." |
Användarnamn/lösenord felaktigt |
EXPIRED_RESET_TOKEN |
"Återställningstoken har gått ut." |
Lösenordsåterställningstoken har gått ut |
OAUTH_FAILED |
"OAuth-processen misslyckades." |
OAuth-autentisering misslyckades |
SAML_NOT_ENABLED |
"SSO (SAML) är inte aktiverat." |
SAML SSO är inte konfigurerat |
SSO_AUTO_PROVISION_DISABLED |
"Automatisk provisionering är inaktiverad." |
Kan inte automatiskt skapa SSO-användare |
Hastighetsbegränsning
Hastighetsbegränsning hanteras av graphql-rate-limit-paketet med olika konfigurationer:
| Begränsningstyp |
Fönster |
Max begärningar |
Tillämpas på |
| 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 |
När hastighetsbegränsningen överskrids kommer du att få ett standard GraphQL-fel med ett meddelande som anger att gränsen överskridits.
System- och interna fel
| Felkod |
Meddelande |
Beskrivning |
INTERNAL_SERVER_ERROR |
"Internt serverfel." |
Generellt fel för icke-säkra fel i produktion |
UNKNOWN_ERROR |
"Okänt fel." |
Oförutsett fel inträffade |
RESOLVER_NOT_FOUND |
"Resolver hittades inte" |
GraphQL-resolver saknas |
FIELD_NOT_IN_SCHEMA |
"Fält finns inte i schemat" |
Begärt fält existerar inte |
Bästa praxis för felhantering
Klientsidehantering
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
}
}
}
Vanliga felscenarier
- Autentisering krävs:
UNAUTHENTICATED - Användaren behöver logga in
- Behörighet nekad:
FORBIDDEN - Användaren saknar nödvändig roll/behörighet
- Resurs hittades inte:
*_NOT_FOUND - Resursen existerar inte eller användaren kan inte få åtkomst till den
- Validering misslyckades:
VALIDATION_ERROR, BAD_USER_INPUT - Kontrollera inmatningsparametrar
- Hastighetsbegränsad: Kontrollera hastighetsbegränsningshuvuden och implementera backoff
- Betalning krävs:
PAYMENT_REQUIRED - Funktionen kräver prenumeration
Relaterad dokumentation