# Respostas e erros

> O envelope de toda resposta, o array errors que vem sempre, os códigos HTTP e o que fazer com cada um, as mensagens de validação e de negócio, o idioma das mensagens e itens removidos.

Toda resposta da API vem no mesmo envelope. Isso deixa um único tratamento servir para todas as chamadas.

## Sucesso

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

`pagination` aparece só em listagens. Ver [Paginação](/api/paginacao).

## Erro

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

- O array `errors` vem **sempre**, mesmo com um erro só.
- `param` diz qual campo causou o erro, quando há um.
- `message` é a mensagem para mostrar.

Assim validação e regra de negócio se tratam pelo mesmo caminho: mostre `errors[].message` ao lado do campo `param`; sem `param`, mostre no topo.

## Os dois tipos de erro

| Tipo | Exemplo | Como reconhecer |
|---|---|---|
| **Validação** | Um campo faltando ou num formato errado | `400`, `param` = o campo, mensagem curta (*"Title is required"*) |
| **Regra de negócio** | Uma ação que o estado atual não permite | `400`, `403`, `404` ou `409`, mensagem que explica (*"Saldo insuficiente…"*) |

## Códigos

| Código | Significa | O que fazer |
|---|---|---|
| `200` / `201` | Deu certo (`201` quando cria) | — |
| `204` | Deu certo, sem corpo (exclusões) | — |
| `400` | Validação falhou, ou falta o `X-CommunityId` (`errors[0].param = "X-CommunityId"`) | Leia `errors` e corrija |
| `401` | Token ausente, inválido ou expirado | Faça login de novo |
| `402` | O pagamento foi recusado | Mostre a mensagem ao comprador |
| `403` | Sem permissão: papel insuficiente, ou o espaço restringe quem cria | Confira o papel e o `X-CommunityId` |
| `404` | Não existe, foi removido, é de outra comunidade, ou o caminho é um dos antigos com `/communities/{communityId}/` | Confira o id, a comunidade e o [caminho](/api/x-community-id#os-caminhos-que-mudaram) |
| `409` | Conflito com o estado atual | Leia a mensagem |
| `429` | Muitas tentativas (ex.: 10 códigos de cupão inválidos em 15 minutos) | Espere alguns minutos |
| `500` | Erro interno | Tente de novo; persistindo, escreva para o suporte |

## Exemplos reais

| Situação | Resposta |
|---|---|
| Listar produtos sem o header `X-CommunityId` | `400` · *Indique a comunidade no cabeçalho X-CommunityId.*, com `param: "X-CommunityId"` |
| Criar espaço numa secção que não existe | `400` · *Secção não encontrada ou não pertence a esta comunidade.* |
| Criar módulo de curso num curso que não existe | `404` · *Curso não encontrado.* |
| Membro publicando num espaço "Equipa" | `403` · *Apenas membros da equipa (admin, proprietário, moderador) podem realizar esta ação* |
| Administrador alterando um proprietário | `403` · *Só um owner ou um SuperAdmin pode remover, rebaixar ou alterar um owner.* |
| Tirar de um plano um adicional com subscritores | `409` · *Não é possível tirar este adicional do plano…* |

Mais exemplos, na ordem em que aparecem ao montar algo, em [Ordem de criação](/api/ordem-de-criacao).

## Idioma das mensagens

As mensagens vêm no idioma do header `Accept-Language` (`pt-BR`, `en-US`, `es-ES`, `it-IT`, `de-DE` e as outras variantes). Algumas validações de formato ainda respondem em inglês.

## Item de outra comunidade

Um item que pertence a outra comunidade responde **404**, igual a um id que não existe. A API não diz que o item existe noutro lugar: para quem chama, ele não existe na comunidade do `X-CommunityId`.

| Quando | Resposta |
|---|---|
| A rota indica um espaço de outra comunidade (`?spaceId=`, o espaço de um curso ou de uma chamada) | `404` · `space.notFound` (*Espaço não encontrado*) |
| A rota indica um item de outra comunidade (ler um conteúdo, os comentários, os participantes de um evento) | `404` · `common.notFound` (*Não encontrado*) |
| Editar, eliminar, comentar, reagir ou fixar conteúdo, evento ou estado de outra comunidade | `404` · a mensagem do módulo (`content.notFound`, `event.notFound`, `status.notFound`, `course.notFound`) |

Ser proprietário, administrador ou moderador numa comunidade não dá acesso a nada de outra, nem enviando o header da sua. Se o item é da comunidade e mesmo assim responde 404, confirme se o `X-CommunityId` é o da comunidade certa.

## Itens removidos

A API não apaga de verdade: itens eliminados são marcados como removidos e deixam de aparecer. Por isso um id eliminado responde **404**, como se nunca tivesse existido.

## Com o SDK

O SDK lança `MemberfyError` com `.status`, `.body` (o envelope inteiro) e `.errors`. Ver [SDK JavaScript](/api/sdk-js).

## Relacionados

- [Autenticação](/api/autenticacao)
- [X-CommunityId](/api/x-community-id)
- [Ordem de criação](/api/ordem-de-criacao)