Erros

Todo erro tem o formato { codigo, mensagem, campos? }. Use o codigo no seu programa: é estável. A mensagem é para pessoas, em português. O campos só vem no 400 e diz o que há de errado em cada campo.

{
  "codigo": "INVALIDO",
  "mensagem": "Confira os dados informados.",
  "campos": {
    "nome": "Campo obrigatório."
  }
}

Os códigos comuns

Status	Código	Quando
400	`INVALIDO`	Corpo ou parâmetro inválido. Veja `campos`.
400	`CHAVE_IDEMPOTENCIA_INVALIDA`	A `Idempotency-Key` não tem de 1 a 255 caracteres visíveis, sem espaços.
401	`TOKEN_INVALIDO`	Sem token, token desconhecido, revogado ou expirado.
403	`SEM_PERMISSAO`	A pessoa não pode fazer isto no escritório, ou não tem lá a permissão de usar a API.
403	`TOKEN_SO_LEITURA`	Escrita com token só de leitura.
403	`TOKEN_BLOQUEADO`	A administração do escritório do caminho bloqueou o token. Nos outros, ele continua.
403	`TOKEN_SEM_ESCOPO`	Token de escritório em uma operação que não foi marcada ao gerá-lo.
403	`TOKEN_AUTOR_INATIVO`	Token de escritório cuja pessoa que o gerou não está mais ativa nele.
404	`NAO_ENCONTRADO`	Não existe, ou está fora do alcance da pessoa.
404	`ESCRITORIO_NAO_ENCONTRADO`	O código no caminho não é de um escritório em que a pessoa é membro ativo. Escritório de outros e código que não existe dão a mesma resposta.
409	`TENTE_NOVAMENTE`	Outra pessoa alterou isto ao mesmo tempo.
409	`CPF_EM_USO`	O CPF, o CNPJ (`CNPJ_EM_USO`) ou o número CNJ (`NUMERO_EM_USO`) já está em outro cadastro; veja `cliente` ou `processo`, quando você pode vê-los.
413	`CORPO_GRANDE`	O corpo da requisição é grande demais.
422	`CHAVE_IDEMPOTENCIA_REUTILIZADA`	A `Idempotency-Key` já foi usada com outro pedido.
429	`LIMITE_TOKEN`	Mais de 120 requisições no minuto.
503	`SISTEMA_OCUPADO`	O sistema está ocupado. Tente em instantes.

Regras de negócio têm códigos próprios, descritos em cada endpoint, como CONFIRMACAO_NECESSARIA e STATUS_TRAVADO.

Reenvio seguro (Idempotency-Key)

Se a conexão cair antes da resposta, você não sabe se o cadastro foi criado. Nas criações (os POST que gravam), envie o cabeçalho Idempotency-Key com uma chave única por operação, como um UUID. Se o mesmo pedido for reenviado com a mesma chave em até 24 horas, a resposta da primeira vez volta, com o cabeçalho Idempotent-Replayed: true, e nada é criado de novo.

A chave vale por token e por escritório. Pedido diferente com a mesma chave dá 422 CHAVE_IDEMPOTENCIA_REUTILIZADA.
Só respostas de sucesso ficam guardadas: se a primeira tentativa falhou, a nova executa.
Se receber 409 TENTE_NOVAMENTE, reenvie com a mesma chave.
A chave só vale em chamadas com token, pessoal ou de escritório. Com a sessão do portal, ela é ignorada.
Os 409 CPF_EM_USO, CNPJ_EM_USO e NUMERO_EM_USO não melhoram com reenvio: corrija o dado, ou use o cadastro que já existe.
O MCP não usa a chave.