Cenários de erro 400 (BadRequest) — Empresas e inscrições

Esta página lista os cenários em que a API de gerenciamento de empresas responde HTTP 400 (BadRequest) ao criar ou atualizar empresa, inscrição municipal, inscrição estadual e certificado digital. As mensagens e os códigos abaixo foram conferidos contra o código da API.

Versões

As seções de inscrição municipal, inscrição estadual e certificado valem para /v2 e /v3 (mesmos endpoints e mensagens). A seção Empresa vale para POST /v2/companies; na V3, as validações diretas também usam a lista de erros — ex.: {"errors":[{"code":40001,"message":"company is null"}]}.

Como interpretar o corpo do erro 400

A API usa três formatos de corpo diferentes, dependendo de onde a validação ocorre:

Formato 1 — texto simples (validações diretas)

Validações de parâmetros e de presença feitas no início da requisição retornam apenas uma string JSON:

"Company is null"

Exemplos: "company_id is null or empty", "limit must be less than 50", "File extension is not valid (.pfx or .p12)".

Formato 2 — lista de erros (validações de negócio)

Regras de negócio retornam um envelope com código + mensagem:

{ "errors": [ { "code": 40032, "message": "federal tax number is not valid" } ] }

• O código é específico em alguns casos (ex.: 40032 CNPJ inválido, 40003 IE inválida) e 40001 na maioria dos demais.
• Apenas o primeiro erro é retornado por vez — corrija um e reenvie para ver o próximo.

Formato 3 — ProblemDetails (formato/desserialização)

Corpo malformado, tipo incompatível ou campo obrigatório ausente ([Required]) retornam ProblemDetails (JSON estruturado), antes de qualquer regra de negócio:

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": { "company.Name": ["The Name field is required."] },
  "traceId": "00-…"
}

nota

Os campos obrigatórios de formato (ex.: name, address, address.street, address.number) são validados pelo formato (Formato 3) antes das regras de negócio. As regras de negócio (Formato 2) só aparecem quando o corpo já está bem-formado e completo.

Empresa (POST /v2/companies)

Cenário	Condição	Corpo / mensagem	Código	Formato
company ausente/nulo	company não enviado	"Company is null"	—	1 (texto)
name ausente	company.name não enviado	company.Name: "The Name field is required."	—	3
address ausente	company.address não enviado	company.Address: "The Address field is required."	—	3
address.street/number ausente	endereço incompleto	"The Street field is required." / "The Number field is required."	—	3
taxRegime inválido	valor fora do enum	$.company.taxRegime: "The JSON value could not be converted…"	—	3
CNPJ inválido	federalTaxNumber com DV inválido (e endereço completo)	federal tax number is not valid	40032	2

dica

taxRegime válidos: LucroReal, LucroPresumido, SimplesNacional, SimplesNacionalExcessoSublimite, MicroempreendedorIndividual, Isento, None.

Inscrição municipal (POST /v2/companies/{id}/municipaltaxes)

Cenário	Condição	Corpo / mensagem	Código	Formato
state da cidade ausente	municipalTax.city.state vazio	state is null or empty	40001	2
environment inválido	valor fora do enum	$.municipalTax.environment: "The JSON value could not be converted…"	—	3
specialTaxRegime inválido	valor fora do enum	$.municipalTax.specialTaxRegime: "…could not be converted…"	—	3

atenção

Cidade ausente (municipalTax.city não enviado) retorna HTTP 404 (Not Found), não 400, com corpo {"errors":[{"code":40401,"message":"40044\|city is null"}]}. Envie sempre o objeto city com code, name, state e country.

Enums: environment ∈ Development/Production/Staging; specialTaxRegime ∈ Nenhum/MicroempresaMunicipal/Estimativa/SociedadeDeProfissionais/Cooperativa/MicroempreendedorIndividual/MicroempresarioEmpresaPequenoPorte/Automatico.

Inscrição estadual (POST /v2/companies/{id}/statetaxes)

Cenário	Condição	Corpo / mensagem	Código	Formato
taxNumber ausente	stateTax.taxNumber não enviado	stateTax.TaxNumber: "The TaxNumber field is required."	—	3
type inválido	valor fora do enum	$.stateTax.type: "…could not be converted…"	—	3
code (UF) inválido	valor fora do enum	$.stateTax.code: "…could not be converted…"	—	3
code (UF) ausente/ inválido (negócio)	UF não reconhecida	state code is not valid	40001	2
IE (taxNumber) inválida	número de IE não válido para a UF	tax number is not valid	40003	2

atenção

O objeto stateTax é obrigatório no corpo. Enums: type ∈ Default/NFe/NFCe; code (UF) ∈ siglas dos estados (SP, RJ, …).

Certificado digital (POST /v2/companies/{id}/certificates, multipart)

Cenário	Condição	Corpo / mensagem	Código	Formato
File ausente	arquivo não enviado	File: "The File field is required."	—	3
Password ausente	senha não enviada	password: "The Password field is required."	—	3
Extensão inválida	arquivo não é .pfx/.p12	"File extension is not valid (.pfx or .p12)"	—	1 (texto)
Empresa inativa	empresa não ativa	company is not active	40019	2
Certificado expirado	validade no passado	Certificate expired	40001	2
Senha incorreta	senha não abre o certificado	Certificate password is invalid	40001	2

atenção

Envie um arquivo .pfx/.p12 válido e a senha correta — um certificado corrompido ou ilegível pode falhar no processamento. Confirme a validade e o tipo (e-CNPJ) do certificado antes do upload.

Empresa com CNPJ alfanumérico

Pelas rotas /v2, chamadas a municipaltaxes, statetaxes e certificates de uma empresa com CNPJ alfanumérico retornam 400 com {"errors":[{"code":40002,"message":"Esta empresa contém CNPJ alfanumérico e requer a API v3; as rotas v1/v2 não suportam CNPJ alfanumérico."}]}. Use as mesmas rotas em /v3.

Veja também

• Solução de erros 400 — Empresas
• Visão geral — Gerenciamento de empresas
• API de inscrições municipais

Para IA / LLMs

• Cobertura: cenários de HTTP 400 ao criar/atualizar empresa, inscrição municipal/estadual e certificado (API de contribuintes v2).
• Não parafrasear: as colunas "mensagem" e "code" são literais retornados pela API.
• Três formatos de corpo: texto simples (validações diretas), { "errors": [ { "code", "message" } ] } (regras de negócio; código 40001 na maioria, específico em alguns; só o primeiro erro por vez), e ProblemDetails (formato/[Required]/enum).
• Atenção: cidade ausente na inscrição municipal retorna 404, não 400.
• Atualizado: 2026-09-23 por conferência contra o código da API (dfetech-tax-payers-api).