Erros - weve

Toda falha responde com o mesmo envelope — na API REST e no webhook de venda, no corpo da resposta. No MCP, o mesmo código volta no texto do erro da ferramenta — erro 422 (missing_field): … — ver Conectar agentes.

{
  "error": {
    "code": "invalid_signature",
    "message": "a assinatura não confere com o segredo desta conexão"
  }
}

Trate pelo code, nunca pela message. O código é estável e não muda sem aviso; a mensagem é diagnóstico para humano e pode ser reescrita a qualquer momento.

Códigos

Código	HTTP	O que aconteceu
`invalid_param`	400	Parâmetro com formato errado (um `id` que não é UUID, um `limit` que não é número)
`invalid_body`	400	Corpo não é JSON válido, traz campo desconhecido, ou passa de 1 MiB
`unauthorized`	401	Chave ausente, inválida, vencida ou revogada
`invalid_signature`	401	A senha ou a assinatura do webhook de venda não confere com a da conexão
`feature_not_in_plan`	402	O recurso não faz parte do plano do club
`insufficient_scope`	403	A chave ou a conexão não tem o escopo `write`
`forbidden`	403	Quem criou a chave ou conectou age no club, mas não o administra, e a operação exige isso
`agent_access_disabled`, `agent_access_admins_only`	403	O club desligou o acesso por chave e agentes, ou o deixou só para quem administra (Ajustes › MCP para IA)
`connection_not_found`	404	Endereço de webhook de venda desconhecido, ou conexão desligada
`…_not_found` (`course_not_found`, `student_not_found`, …)	404	O recurso não existe neste club — de outro club responde igual
`…_taken` (`email_taken`, `slug_taken`, …)	409	Já existe outro recurso com aquele valor único
`student_anonymized`	409	O aluno foi removido, e a operação daria acesso a uma conta que já não é de ninguém
`enrollment_already_active`	409	O aluno já tem outra matrícula ativa da mesma entrega
`missing_field`	422	Campo obrigatório ausente ou vazio
`invalid_…` (`invalid_type`, `invalid_release`, …)	422	O campo veio, mas com um valor que não é aceito; a mensagem diz qual
`rate_limited`	429	Teto de requisições atingido; respeite o `Retry-After` — ver Limites
`internal_error`	500	Falha nossa; o detalhe está no rastreio, nunca no corpo

Por que o 500 não explica nada

A resposta de internal_error é sempre genérica, sem o erro real. Isso é deliberado: mensagem de banco de dados conta a quem está do outro lado detalhes de esquema e de implementação. O diagnóstico completo fica no nosso log, correlacionado pelo X-Request-Id da resposta — se você abrir um chamado, é esse valor que encurta a investigação.