# 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

```json
{
  "success": true,
  "message": "Login successful.",
  "data": { },
  "pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7 }
}
```

`pagination` compare solo negli elenchi. Vedi [Paginazione](/api/paginacao).

## Errore

```json
{
  "success": false,
  "message": "Valid email is required",
  "errors": [{ "param": "email", "message": "Valid email is required" }]
}
```

- L'array `errors` arriva **sempre**, anche con un solo errore.
- `param` indica 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](/api/x-community-id#i-percorsi-cambiati) |
| `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](/api/ordem-de-criacao).

## 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](/api/sdk-js).

## Correlati

- [Autenticazione](/api/autenticacao)
- [X-CommunityId](/api/x-community-id)
- [Ordine di creazione](/api/ordem-de-criacao)