Risposte ed errori
L'involucro di ogni risposta, l'array errors che arriva sempre, i codici HTTP e che cosa fare con ciascuno, i messaggi di validazione e di regola di business, la lingua dei messaggi e gli elementi rimossi.
Ogni risposta dell'API arriva nello stesso involucro. Così un'unica gestione vale per tutte le chiamate.
Successo
{
"success": true,
"message": "Login successful.",
"data": { },
"pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7 }
}
pagination compare solo negli elenchi. Vedi Paginazione.
Errore
{
"success": false,
"message": "Valid email is required",
"errors": [{ "param": "email", "message": "Valid email is required" }]
}
- L'array
errorsarriva sempre, anche con un solo errore. paramindica quale campo ha causato l'errore, quando ce n'è uno.messageè il messaggio da mostrare.
In questo modo validazione e regole di business si gestiscono nello stesso modo: mostra errors[].message accanto al campo param; senza param, mostralo in alto.
I due tipi di errore
| Tipo | Esempio | Come riconoscerlo |
|---|---|---|
| Validazione | Un campo mancante o in un formato sbagliato | 400, param = il campo, messaggio breve ("Title is required") |
| Regola di business | Un'azione che lo stato attuale non consente | 400, 403, 404 o 409, con un messaggio che spiega ("Saldo insufficiente…") |
Codici
| Codice | Significato | Cosa fare |
|---|---|---|
200 / 201 | Riuscito (201 quando crea) | — |
204 | Riuscito, senza corpo (eliminazioni) | — |
400 | Validazione fallita, oppure manca l'X-CommunityId (errors[0].param = "X-CommunityId") | Leggi errors e correggi |
401 | Token assente, non valido o scaduto | Rifai il login |
402 | Il pagamento è stato rifiutato | Mostra il messaggio all'acquirente |
403 | Nessun permesso: ruolo insufficiente, oppure lo spazio limita chi può creare | Controlla il ruolo e l'X-CommunityId |
404 | Non esiste, è stato rimosso, appartiene a un'altra community, oppure il percorso è uno dei vecchi con /communities/{communityId}/ | Controlla l'id, la community e il percorso |
409 | Conflitto con lo stato attuale | Leggi il messaggio |
429 | Troppi tentativi (es.: 10 codici coupon non validi in 15 minuti) | Aspetta qualche minuto |
500 | Errore interno | Riprova; se persiste, scrivi al supporto |
Esempi reali
| Situazione | Risposta |
|---|---|
Elencare i prodotti senza l'header X-CommunityId | 400 · Indica la community nell'header X-CommunityId., con param: "X-CommunityId" |
| Creare uno spazio in una sezione che non esiste | 400 · Seção não encontrada ou não pertence a esta comunidade. |
| Creare un modulo in un corso che non esiste | 404 · Course not found |
| Un membro che pubblica in uno spazio "Staff" | 403 · Solo lo staff (amministratore, proprietario, moderatore) può eseguire questa azione |
| Un amministratore che modifica un proprietario | 403 · Solo un owner o un SuperAdmin può rimuovere, declassare o modificare un owner. |
| Togliere da un piano un componente aggiuntivo con abbonati | 409 · Non è possibile togliere questo componente aggiuntivo dal piano… |
Altri esempi, nell'ordine in cui compaiono quando costruisci qualcosa, in Ordine di creazione.
Lingua dei messaggi
I messaggi arrivano nella lingua dell'header Accept-Language (pt-BR, en-US, es-ES, it-IT, de-DE e le altre varianti). Alcune validazioni di formato, e alcuni messaggi non ancora tradotti, rispondono ancora in inglese o in portoghese.
Elemento di un'altra community
Un elemento che appartiene a un'altra community risponde 404, come un id che non esiste. L'API non rivela che l'elemento esiste altrove: per chi chiama, non esiste nella community dell'X-CommunityId.
| Quando | Risposta |
|---|---|
La rotta indica uno spazio di un'altra community (?spaceId=, lo spazio di un corso o di una call) | 404 · space.notFound |
| La rotta indica un elemento di un'altra community (leggere un contenuto, i suoi commenti, i partecipanti di un evento) | 404 · common.notFound |
| Modificare, eliminare, commentare, reagire o fissare contenuti, un evento o uno stato di un'altra community | 404 · il messaggio del modulo (content.notFound, event.notFound, status.notFound, course.notFound) |
Essere proprietario, amministratore o moderatore in una community non dà accesso a nulla di un'altra, nemmeno inviando l'header della propria. Se l'elemento è della community e risponde comunque 404, controlla che l'X-CommunityId sia quello della community giusta.
Elementi rimossi
L'API non cancella davvero: gli elementi eliminati vengono contrassegnati come rimossi e non compaiono più. Per questo un id eliminato risponde 404, come se non fosse mai esistito.
Con l'SDK
L'SDK lancia MemberfyError con .status, .body (l'involucro completo) ed .errors. Vedi SDK JavaScript.