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
{
"success": true,
"message": "Login successful.",
"data": { },
"pagination": { "page": 1, "limit": 20, "total": 137, "totalPages": 7 }
}
pagination aparece só em listagens. Ver Paginação.
Erro
{
"success": false,
"message": "Valid email is required",
"errors": [{ "param": "email", "message": "Valid email is required" }]
}
- O array
errorsvem sempre, mesmo com um erro só. paramdiz 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 |
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.
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.