---
title: "Cenários de erro 400 (BadRequest) — Empresas e inscrições"
description: "Cenários em que a API de empresas retorna HTTP 400 ao criar/atualizar empresa, inscrição municipal/estadual e certificado — com o corpo real e a correção."
source_url: https://nfe.io/docs/documentacao/gerenciamento-empresas/duvidas/erros-e-status/cenarios-de-badrequest-empresas
last_updated: 2026-09-25
---

# 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.

:::note 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**:

```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**:

```json
{ "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:

```json
{
  "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-…"
}
```

:::note
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 |

:::tip
`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 |

:::warning
**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 |

:::warning
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 |

:::warning
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.
:::

:::warning 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](./solucao-de-erros-400-empresas.md)
- [Visão geral — Gerenciamento de empresas](../../gerenciamento-empresas-resumo.md)
- [API de inscrições municipais](../../gerenciamento-inscricao-municipal.md)

## 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).