Tratamento de erros

Sempre trate o corpo da resposta no seu cliente: esta API tem alguns comportamentos que não seguem a convenção HTTP padrão, detalhados abaixo.

'Não encontrado' NÃO é 404 aqui

Um identificador inexistente não gera 404 nesta API. Isso vale para GET /v3/liquidacoes/{id}, GET /acordos/{idAcordo}, GET /v1/processamento/status/{lote} e GET /v2/processamento/{lote}: todos retornam 200 OK, com [] (array vazio) ou um objeto com todos os campos null. Se seu código verifica status === 404 para decidir "não achei", ele nunca vai disparar aqui. Verifique se o corpo voltou vazio/nulo, não o status.

Códigos de status

Código	Significado	O que fazer
`200`	OK	Sucesso em leitura, inclusive quando o identificador não existe (ver aviso acima).
`201`	Criado	Lote aceito para processamento assíncrono (inclusão de aluno/parcela). Acompanhe pelo `id` retornado. A validação de conteúdo (enum, formato, regra de negócio) acontece depois, de forma assíncrona: o `201` não significa que os dados eram válidos, só que o lote foi recebido.
`400`	Requisição inválida	Corpo malformado, JSON quebrado, ou campo obrigatório de nível de lote faltando (ex.: array `parcelas` vazio). Veja o formato abaixo.
`401`	Não autenticado	Header `apikey` ausente ou inválido.

Outros códigos possíveis

Os códigos abaixo seguem a convenção HTTP padrão, mas não fazem parte do comportamento confirmado desta API:

Código	Quando esperar
`403`	Chave sem permissão de acesso ao recurso.
`404`	Não usado por esta API para "recurso não encontrado": identificador inexistente retorna `200` (ver aviso acima).
`422`	Não usado: dados inválidos em enum/formato/tipo são aceitos com `201` e reportados depois, de forma assíncrona (ver seção abaixo).
`429`	Limite de requisições, se houver algum configurado.
`500`	Erro interno do servidor.

Formato do erro

O formato não é o mesmo para todo código. Existem duas variações:

401, sem o campo error

{
  "statusCode": 401,
  "message": "Unauthorized"
}

400, com o campo error (message também pode vir como array)

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": "Pelo menos uma parcela deve possuir uma propriedade preenchida!"
}

400, variante com message em array (validação de múltiplos campos)

{
  "statusCode": 400,
  "error": "Bad Request",
  "message": ["parcelas should not be empty"]
}

Seu cliente deve tratar message como string OU array de strings, nunca assuma um formato fixo.

Erros de validação por item (dentro de um lote)

Um lote de alunos/parcelas pode ser aceito (HTTP 201) e ainda assim ter itens individuais que falharam na validação. Esses erros não aparecem no corpo da resposta imediata: eles aparecem quando você consulta GET /v1/processamento/status/{lote} (ou v2/processamento/{lote}), no array validacao de cada registro:

"validacao": [
  {
    "nome": "cpf",
    "valido": false,
    "tipo": "RESPONSAVEL_FINANCEIRO",
    "mensagem": "CPF inválido: 679...",
    "valor": "679..."
  }
]

nome: campo que falhou.
tipo: se o campo é do ALUNO ou do RESPONSAVEL_FINANCEIRO.
valido: false indica que esse campo específico bloqueou o processamento do item.
mensagem: motivo, pronto para log/exibição.

Trate cada item do lote de forma independente: um item com validacao inválida não invalida os demais itens do mesmo lote.

Boas práticas

Não confie em status HTTP pra "não encontrado": confira se o corpo voltou vazio/nulo (ver aviso no topo da página).
Backoff exponencial em erros de rede, timeout ou 5xx é sempre boa prática defensiva.
Log do message para diagnóstico, mas nunca logue a apikey. Trate message como string ou array.
Falha parcial de lote: identifique os itens com erro pelo array validacao do status do processamento e reenvie apenas eles.

Códigos de status

Outros códigos possíveis

Formato do erro

Erros de validação por item (dentro de um lote)

Boas práticas

Nesta página