Erros

A API do Lumen ERP usa os códigos de status HTTP convencionais: 2xx indicam sucesso, 4xx indicam um problema na requisição e 5xx indicam uma falha do servidor. Todas as respostas de erro são JSON, com ou sem o cabeçalho Accept: application/json.

Códigos de status HTTP

200 / 201

OK / Created

A requisição foi bem-sucedida. 201 indica que um registro foi criado.

400

Bad Request

Cabeçalhos de autenticação ausentes, ou dados inválidos nos endpoints que validam com 400 (veja os formatos abaixo).

401

Unauthorized

Credenciais inválidas ou revogadas. Veja o guia Autenticação.

403

Forbidden

A API do cliente está desativada; o app do Portal do Parceiro não está aprovado ou está suspenso; uma chave de teste foi usada em produção ("code": "SANDBOX_HOST") ou uma chave de produção no sandbox; ou o módulo é do plano Gestão Escolar (ERP) e o cliente está no plano simplificado ("code": "ERP_REQUIRED").

404

Not Found

A rota não existe, o {cnpj} não pertence ao cliente ou o registro pedido não foi encontrado.

409

Conflict

O pedido conflita com o estado atual: registro duplicado (disciplina com o mesmo nome), disciplina em uso, quadro de horários com aulas pendentes, curso não publicado etc.

422

Unprocessable Entity

Dados inválidos nos endpoints que validam com 422, ou operação bloqueada por uma regra de negócio (veja Consistência de Dados).

429

Too Many Requests

Limite de requisições por minuto excedido. Aguarde o tempo indicado no cabeçalho Retry-After.

500

Internal Server Error

Falha inesperada ao gravar; a mensagem costuma ser "Operação não realizada.". Pode ser repetida com segurança nas leituras; nas gravações, consulte o registro antes de repetir.

503

Service Unavailable

A plataforma está em manutenção (uma atualização em andamento). Tente novamente em alguns minutos.

Erros de validação

O formato depende do endpoint; a página de cada um mostra o seu. Na prática, trate 400 e 422 como erro de validação e leia errors, que pode ser uma lista de mensagens ou um objeto com as mensagens de cada campo.

Lista de mensagens (turmas, aulas, agendas, ano letivo e calendário, disciplinas, formas de avaliação, matrículas, notas, fotos, ocorrências, quadro de horários) 400

{
  "success": false,
  "errors": [
    "O campo name é obrigatório.",
    "O campo birthdate deve ser uma data válida."
  ]
}

Mensagens por campo (responsáveis, professores, coordenadores, secretários, portões, carga horária, plano de curso, plano pedagógico, diário, conselho de classe, horários) 422

{
  "success": false,
  "errors": {
    "subject_id": ["O campo subject id é obrigatório."]
  }
}

Mensagens por campo, sem success (frequência por aula, visitantes, CRM, metas, eventos, biblioteca, cursos online, pré-matrícula, WhatsApp) 422

{
  "message": "O campo name é obrigatório.",
  "errors": {
    "name": ["O campo name é obrigatório."]
  }
}

Demais erros

Recursos não encontrados, conflitos e regras de negócio trazem uma mensagem em português, pronta para exibir ao usuário. Quando a recusa vem de uma regra de Consistência de Dados, a resposta traz também code, estável para tratamento no seu código.

Recurso não encontrado 404

{
  "success": false,
  "message": "Aluno não encontrado."
}

Operação bloqueada por dados dependentes 422

{
  "success": false,
  "code": "HAS_ENROLLMENTS",
  "message": "A turma possui alunos matriculados e não pode ser removida."
}

Módulo fora do plano do cliente 403

{
  "success": false,
  "code": "ERP_REQUIRED",
  "message": "Módulo disponível apenas para clientes do plano Gestão Escolar (ERP)."
}

Rota inexistente 404

{
  "message": "Parâmetros incorretos ou não encontrados."
}

Limite de requisições excedido 429

{
  "message": "Too Many Attempts."
}