Rascunho em revisão — esta página ainda não é indexada pelos buscadores.
Erros comuns ao enviar dados ao PNCP e como corrigir
Os erros mais comuns da API do PNCP são de conformidade entre modalidade, instrumento convocatório, amparo legal, modo de disputa e critério de julgamento (HTTP 422), de formato de data e de tipo de conteúdo do envio (HTTP 400 e 415), de registro pai inexistente, como contratação não encontrada, e de plataforma sem autorização para o órgão.
Atualizado em · Escrito por Mário Dias · Revisado por [PREENCHER: nome do revisor técnico], [PREENCHER: cargo — ex.: responsável técnico pela integração com o PNCP]
Como o PNCP devolve os erros?
O Manual de Integração lista, para cada serviço, os códigos de retorno: 200 ou 201 em caso de sucesso, e 400 (Bad Request), 404 (não encontrado), 422 (Unprocessable Entity) e 500 (Internal Server Error) em caso de erro. Nos registros do MeuPNCP, o corpo de erro do PNCP aparece em dois formatos:
{"erros":[{"nomeCampo":"itensCompra[0].descricao","mensagem":"Descrição do item não informada."}]}{
"timestamp": "2024-12-30T17:18:52.383-03:00",
"status": "422",
"error": "422 UNPROCESSABLE_ENTITY",
"message": "Atributo 'catalogoCodigoItem' em branco ou vazio.",
"path": "/pncp-api/v1/orgaos/…/compras"
}A plataforma deve guardar o corpo completo da resposta, e não só o código HTTP: é a mensagem que diz o que corrigir. O MeuPNCP grava em cada envio a URL, o corpo enviado, o código HTTP e o retorno do PNCP.
O que significa "Não há conformidade" no PNCP?
O PNCP valida combinações entre domínios. O manual descreve as regras de conformidade entre instrumento convocatório, modalidade e amparo legal (seção 5.18), entre instrumento convocatório e modo de disputa (5.19), entre modalidade e critério de julgamento (5.22) e entre modalidade e fonte orçamentária (5.26), e avisa que o portal "não receberá novas contratações ou permitirá a retificação se os campos informados não estiverem em conformidade" (seção 6.3.1).
| Mensagem real do PNCP | Regra (manual) | Correção |
|---|---|---|
| "Não há conformidade entre o Instrumento Convocatório, Modalidade e Amparo Legal informados." (HTTP 422) | 5.18 | consulte as combinações válidas no serviço de conformidade e ajuste tipoInstrumentoConvocatorioId, modalidadeId ou amparoLegalId |
| "Não há conformidade entre o Instrumento Convocatório e o Modo de Disputa informados." | 5.19 | ajuste modoDisputaId ao instrumento (ex.: contratação direta costuma usar modo "Não se aplica" ou "Dispensa Com Disputa") |
| "Não há conformidade entre a modalidade da contratação e o critério de julgamento do item nº …" | 5.22 | corrija criterioJulgamentoId do item para um critério aceito pela modalidade |
| "Tipo de item da contratação inválido para contratação na modalidade leilão: S" | regras de item por modalidade | em leilão, revise materialOuServico do item |
| "Categoria de compra de item inválida para a modalidade de compra" | regras de item por modalidade | ajuste itemCategoriaId à modalidade |
[PREENCHER: revisor técnico — confirmar no serviço de conformidade 5.19 quais modos de disputa são aceitos para cada instrumento antes de manter o exemplo entre parênteses]
Em 03/11/2026, os domínios oficiais tinham 19 modalidades, 6 modos de disputa, 15 critérios de julgamento ativos, 4 instrumentos convocatórios ativos e 191 amparos legais. O MeuPNCP consulta as combinações válidas antes do envio, o que evita o erro 422. Os termos estão explicados no glossário do PNCP, e os códigos válidos de cada tabela em tabelas de domínio do PNCP.
Por que o PNCP recusa a data informada?
| Mensagem real | Causa | Correção |
|---|---|---|
| "Atributo 'dataAberturaProposta' inválido." | formato de data e hora diferente do esperado | envie no formato ISO 2026-02-01T10:00:00, como no exemplo oficial |
| "Não foi possível processar a requisição, dados inválidos: .dataAberturaProposta" | valor que não pôde ser convertido | verifique se a data não está vazia ou com fuso/formato misturado |
| "Data de abertura posterior à data de encerramento." | datas invertidas | a abertura das propostas deve ser anterior ao encerramento |
| "Data início da vigência posterior à data fim da vigência." | vigência invertida (contrato ou ata) | confira dataVigenciaInicio e dataVigenciaFim |
| "Atributo 'dataVigenciaInicio' inválido." | data ausente ou fora do formato AAAA-MM-DD (termo) | envie a data no formato de data simples |
Atenção à diferença: na contratação, dataAberturaProposta e dataEncerramentoProposta levam data e hora; no contrato, na ata e no termo, as datas de assinatura e de vigência são só data (exemplos do Swagger oficial).
O que fazer com erro 415 "Content type not supported"?
O erro 415 indica que o serviço recebeu um tipo de conteúdo diferente do que aceita. Os serviços de inserção de contratação, ata e contrato e os de documentos são multipart/form-data, com uma parte JSON e uma parte de arquivo; os de retificação, exclusão, itens, resultados, termos, empenhos e PCA recebem application/json (conferido no Swagger oficial em 03/11/2026). Mensagens reais:
- "Content type 'application/json' not supported" (HTTP 415, ao enviar ata como JSON puro);
- "Content type 'application/octet-stream' not supported" (HTTP 415, na retificação de contratação, serviço que espera
application/json); - "Content type 'application/x-www-form-urlencoded;charset=UTF-8' not supported" (envio de contrato, termo ou PCA como formulário).
No multipart/form-data, a parte JSON precisa declarar type=application/json, como no exemplo de cURL do manual: --form 'compra=@"/home/objeto.json";type=application/json'.
Por que o PNCP diz que a compra ou a ata não existe?
Registros filhos usam o ano e o sequencial gerados pelo PNCP para o registro pai. Se o pai não foi publicado, foi excluído ou se o sequencial enviado é o número interno do processo, o PNCP não encontra o registro:
| Mensagem real | Serviço | Correção |
|---|---|---|
| "Compra não encontrada: …-1-000018/2025" (HTTP 422) | contrato | publique a contratação e use anoCompra e sequencialCompra do número de controle |
| "Compra não cadastrada." | ata | idem: a ata depende da contratação publicada |
| "Contratação não cadastrada." | itens da contratação | envie os itens para uma contratação existente |
| "Ata não cadastrada." (HTTP 404) | documento da ata | confirme o sequencial da ata devolvido na inclusão |
| "Contrato não cadastrado." | termo de contrato | publique o contrato antes do termo |
Como resolver "Serviço sobre ente não autorizado para o usuário"?
A mensagem "Serviço sobre ente … não autorizado para o usuário …" indica que a plataforma não está autorizada a publicar pelo CNPJ informado. Em produção, a autorização é dada pelo gestor do órgão na funcionalidade "Gestão de Órgão/Entidade" da Área de Trabalho do PNCP (seção 6.2.9). No ambiente de treinamento, plataformas públicas podem vincular entes autorizados pela API, e plataformas privadas precisam de contato prévio com a central de atendimento e comprovação de vínculo (seção 6.1.5). A inclusão de órgão por plataforma privada também pode ser recusada: "Operação não autorizada. Entre em contato com a administração do Portal PNCP através da central de atendimento."
Já o código 401 (Unauthorized) aparece quando o token está ausente ou expirado. O token JWT vale por 1 hora; a plataforma deve renovar o login antes de expirar (seção 3.2).
Quais erros de campos obrigatórios são mais comuns?
| Mensagem real | Correção |
|---|---|
| "Indicador de Aplicabilidade da Margem de Preferência Normal (aplicabilidadeMargemPreferenciaNormal) não informado ou nulo. Este campo deve ser preenchido com false/0 (Não) ou true/1 (Sim)." | envie false ou true em todos os itens |
| "Código NCM / NBS (ncmNbsCodigo) vazio ou em branco." (HTTP 422) | informe o código NCM (material) ou NBS (serviço) do item quando exigido |
| "Atributo 'catalogoCodigoItem' em branco ou vazio." (HTTP 422) | informe o código do item no catálogo escolhido |
| "Indicador de compra SRP inválido." (HTTP 400) | envie srp como booleano |
| "Código do porte da empresa fornecedora não informado." (HTTP 400, resultado do item) | informe porteFornecedorId |
| "Código Ibge do município inválido." (HTTP 400) | use o código IBGE de 7 dígitos, só números |
| "Forneça o NI do fornecedor subcontratado." | complete ou remova os dados de subcontratação |
| "CPF ou CNPJ do fornecedor com DV inválido" | valide o dígito verificador e mantenha zeros à esquerda |
Como tratar registros e arquivos duplicados?
O PNCP impede inclusões repetidas. Para contratação, a resposta real foi "Inclusão não permitida pois já existe contratação para os parâmetros informados. Id contratação PNCP: …-1-000005/2025" (HTTP 422); para contrato, "Inclusão não permitida pois já existe contrato para os parâmetros informados."; para arquivos, "Este arquivo já foi enviado para o PNCP" (HTTP 400). Nesses casos, a ação certa é retificar o registro existente, usando o número de controle devolvido, e não incluir de novo. Para unidades, "Código da unidade já cadastrado para o órgão." indica que a unidade já existe.
E os erros nos documentos anexos?
Os serviços de documento exigem os cabeçalhos Titulo-Documento e Tipo-Documento-Id. A falta deles gera respostas reais como "Required request header 'Tipo-Documento-Id' for method parameter type Long is not present" e, na validação por campo, "Nome/descrição do arquivo não informado." e "Código de tipo de documento inválido.". O manual limita cada arquivo a 30 MB e lista as extensões aceitas, como pdf, txt, doc, docx, xls, xlsx, odt, zip e 7z (seção 5.16); imagens de item têm limite de 3 MB e até 5 por item (seção 5.21).
Para entender os serviços envolvidos, veja API do PNCP. O guia como publicar no PNCP mostra a ordem correta dos envios, que evita a maior parte dos erros de registro inexistente.
Perguntas frequentes
O que significa erro 422 na API do PNCP?
O código 422 (Unprocessable Entity) indica que a requisição foi entendida, mas viola uma regra de negócio do PNCP, como falta de conformidade entre modalidade e amparo legal, registro duplicado ou campo obrigatório em branco.
Como resolver "Não há conformidade entre o Instrumento Convocatório, Modalidade e Amparo Legal"?
Consulte as combinações válidas no serviço de conformidade do PNCP (seção 5.18 do manual) e ajuste o instrumento convocatório, a modalidade ou o amparo legal da contratação antes de reenviar.
Por que recebo "Content type not supported" ao enviar ao PNCP?
Porque o serviço espera outro formato. Contratação, ata e contrato são enviados como multipart/form-data, com a parte JSON marcada como application/json; retificações, itens, termos e PCA usam application/json.
O que fazer quando o PNCP diz "Compra não encontrada"?
Verifique se a contratação foi publicada e se o contrato ou a ata usam o ano e o sequencial gerados pelo PNCP, e não o número interno do processo.
Por que a API do PNCP retorna 401?
Por falta de token ou token expirado. O JWT obtido em /v1/usuarios/login vale 1 hora e deve ser enviado no cabeçalho Authorization em cada requisição de manutenção.
Qual o tamanho máximo de arquivo aceito pelo PNCP?
30 MB por arquivo nos serviços de documento e 3 MB por imagem de item, com até 5 imagens por item (Manual de Integração, seções 5.16 e 5.21).
Fontes
- Manual de Integração PNCP, versão 2.4 (abril/2026) — seções 3.2, 5.16, 5.18, 5.19, 5.21, 5.22, 5.26, 6.1.5, 6.2.9 e 6.3.1 (conferido em 03/11/2026)
- Documentação técnica (Swagger/OpenAPI) da API do PNCP — produção (conferido em 03/11/2026)
- Tabelas de domínio do PNCP (modalidades, modos de disputa, critérios de julgamento) (conferido em 03/11/2026)
Conteúdo informativo; não substitui orientação jurídica.