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."}]}
Formato de validação por campo (esquema RespostaErroValidacaoDTO do Swagger). Mensagem real.
{
  "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"
}
Formato com mensagem única. Resposta real, com o CNPJ do caminho removido.

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

Mensagens do log de auditoria do MeuPNCP no ambiente de treinamento do PNCP.
Mensagem real do PNCPRegra (manual)Correção
"Não há conformidade entre o Instrumento Convocatório, Modalidade e Amparo Legal informados." (HTTP 422)5.18consulte 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.19ajuste 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.22corrija 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 modalidadeem leilão, revise materialOuServico do item
"Categoria de compra de item inválida para a modalidade de compra"regras de item por modalidadeajuste 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 realCausaCorreção
"Atributo 'dataAberturaProposta' inválido."formato de data e hora diferente do esperadoenvie 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 convertidoverifique se a data não está vazia ou com fuso/formato misturado
"Data de abertura posterior à data de encerramento."datas invertidasa 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 realServiçoCorreção
"Compra não encontrada: …-1-000018/2025" (HTTP 422)contratopublique a contratação e use anoCompra e sequencialCompra do número de controle
"Compra não cadastrada."ataidem: a ata depende da contratação publicada
"Contratação não cadastrada."itens da contrataçãoenvie os itens para uma contratação existente
"Ata não cadastrada." (HTTP 404)documento da ataconfirme o sequencial da ata devolvido na inclusão
"Contrato não cadastrado."termo de contratopublique 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?

Mensagens reais do log de auditoria do MeuPNCP; valores de CPF/CNPJ removidos.
Mensagem realCorreçã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

  1. 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)
  2. Documentação técnica (Swagger/OpenAPI) da API do PNCP — produção (conferido em 03/11/2026)
  3. 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.