Cada erro, explicado num endereço estável.
Esta página é uma referência de operações, não um argumento de venda. Cada classe de erro da API Connect tem aqui uma âncora permanente; as respostas de erro da API apontarão para estes endereços. Encontra a causa provável e a correção — por esta ordem. Voltar à documentação para programadores.
Chave em falta, malformada ou desconhecida
A API autentica exclusivamente através do cabeçalho Authorization: Bearer vgk_… — nunca por cookie de sessão. Uma chave revogada torna-se desconhecida no instante em que é revogada.
A correção. Verifique que o cabeçalho sai mesmo (há proxies que o retiram), que a chave começa por vgk_ e que não foi revogada na consola do gabinete. Como o segredo só é mostrado na criação, uma chave perdida substitui-se, não se recupera.
Chave caducada
Todas as chaves caducam um ano após a criação — a data expire_le está visível na consola do gabinete desde o primeiro dia. O 401 de caducidade é explícito: diz que a chave existiu e já não é válida.
A correção. Crie uma chave nova, mude as suas chamadas para ela, revogue a antiga. Planeie esta substituição nas suas operações em vez de a descobrir: a data é conhecida com um ano de antecedência.
Scope insuficiente
As chaves transportam lecture (leitura, por defeito) e/ou ecriture (escrita). Qualificar um evento exige ecriture; uma chave só de leitura recebe um 403, qualquer que seja o recurso.
A correção. Crie uma chave com o scope necessário — e apenas esse. O menor privilégio é deliberado: uma integração que só lê não tem razão para deter uma chave de escrita.
Não encontrado — ou de outro gabinete
Um 404 significa que o recurso não existe ou pertence a outro gabinete. A API nunca distingue os dois casos: distinguir revelaria o que existe noutro lado. A compartimentação é imposta ao nível da base de dados, não apenas no código aplicacional.
A correção. Confirme o seq no diário do gabinete a que a chave pertence (GET /api/v1/evenements). Se integra vários gabinetes, cada gabinete tem as suas próprias chaves: um seq não viaja entre gabinetes.
Débito excedido
60 pedidos por minuto e por chave, por defeito (ajustável por chave). A resposta transporta Retry-After e os cabeçalhos X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.
A correção. Respeite o Retry-After — nada de repetir de imediato. Bater no limite durante o polling é quase sempre sinal de uma releitura completa: o cursor depuisSeq nunca relê o que já foi lido.
A assinatura não se verifica do seu lado
O seu recetor deve recalcular v1 = HMAC-SHA256(secret, t + "." + body) a partir do corpo bruto recebido e rejeitar qualquer t com mais de 5 min. As falhas clássicas: o corpo re-serializado antes da verificação (um JSON reformatado já não tem os mesmos bytes), um relógio à deriva além da tolerância e uma rotação ignorada — durante 24 h o cabeçalho transporta um v1 por cada segredo ainda válido, e deve aceitar se qualquer um deles corresponder.
A correção. Verifique sobre os bytes brutos, sincronize o relógio (NTP), teste a sua verificação durante uma rotação. Os excertos Node e Python da documentação fazem exatamente isto — copie-os em vez de os reescrever.
Um evento chega duas vezes
A entrega é at-least-once, em lotes de 100 no máximo, pela ordem do diário; o cursor só avança com o seu 2xx, lote a lote. Uma falha depois da receção mas antes de o cursor avançar provoca uma nova entrega — é o contrato, não um defeito.
A correção. O seq é a sua chave de idempotência: processe cada sequência exatamente uma vez e só responda 2xx depois de persistir. Um 2xx precoce seguido de um crash é a única forma de perder um evento.
O diário parece incompleto ou repete-se
depuisSeq é estritamente exclusivo: só os eventos com seq superior são devolvidos, por ordem ascendente, 500 por página no máximo. A resposta devolve prochainSeq, a repassar tal e qual. Uma página mais curta do que limite significa o fim do diário.
A correção. Persista prochainSeq entre execuções e nunca o recalcule por si. Duplicados significam que recomeçou de um cursor demasiado antigo; lacunas significam que saltou uma página falhada sem a repetir.
Parâmetro fora do esquema
Um estado desconhecido, uma disposição fora da lista (planifie, traite, ecarte), um limite não inteiro: a resposta nomeia o campo em causa, e nada mais — as mensagens de erro nunca transportam conteúdo de processos.
A correção. A especificação OpenAPI é a fonte: as enumerações e os limites que declara são os que o servidor impõe, uma vez que é servida por ele.
Scope insuficiente (API de recursos)
Os endpoints de recursos (/clients, /dossiers, documentos, triagem, alertas) exigem um scope fino: clients:*, dossiers:*, pieces:*, criblage:* ou o scope dedicado alertes:qualifier. Uma chave legada lecture concede todos os scopes *:lecture e ecriture todos os *:ecriture — mas alertes:qualifier nunca é herdado: qualificar um alerta é um ato do responsável, delegado ao assinalar esse scope na criação da chave.
A correção. Crie uma chave com exatamente os scopes de que a sua integração precisa — e apenas esses. O detail da resposta nomeia o scope em falta.
Recurso não encontrado — ou de outro gabinete
A mesma regra de #cloisonnement, aplicada aos recursos: um cliente, um processo, um documento ou um alerta que não existe ou que pertence a outro gabinete recebe o mesmo 404. A API nunca separa os dois casos.
A correção. Confirme o identificador nas listagens do gabinete a que a chave pertence. Um identificador nunca viaja de um gabinete para outro.
Cabeçalho Idempotency-Key em falta
Qualquer POST de criação ou de acionamento (cliente, processo, documento, triagem, beneficiários efetivos) exige o cabeçalho Idempotency-Key: uma cadeia estável de 200 caracteres no máximo, uma por operação. Repetir a mesma chave com o mesmo corpo devolve a mesma resposta, sem efeito — a sua proteção contra duplicados num incidente de rede.
A correção. Gere a chave antes da primeira tentativa (um UUID por operação de negócio) e reutilize-a inalterada em cada repetição dessa mesma operação.
Chave de idempotência reutilizada com um corpo diferente
Esta Idempotency-Key já foi utilizada com um corpo diferente nas últimas 24 horas. A chave repete uma resposta, nunca a substitui: reutilizá-la para uma operação nova é quase sempre sinal de uma chave derivada de um contador ou de uma data truncada.
A correção. Uma chave nova para cada operação nova. Nunca derive a chave de dados que se repetem entre operações.
Processo selado: o registo está congelado
Selar congela a cadeia de integridade do processo — é esse o seu valor probatório. Um processo selado já não pode ser editado, já não recebe documentos e já não é re-triado por este canal. Só a qualificação de alertas continua possível: escreve-se off-chain, a cabeça selada nunca se move.
A correção. Nada a «corrigir»: é imutabilidade deliberada. Se os dados tiverem de mudar, isso é uma nova operação de diligência na aplicação, não uma mutação do processo selado.
Formato de documento não aceite
Os documentos comprovativos aceitam PDF, JPG, JPEG, PNG e WEBP — os mesmos formatos da aplicação. A verificação incide na extensão do filename obrigatório: um documento sem nome de ficheiro válido é recusado, qualquer que seja o conteúdo.
A correção. Converta antes de enviar (uma digitalização TIFF ou HEIC converte-se em PDF ou JPEG) e envie o conteúdo em base64 padrão em contenu, com um type entre os códigos estáveis a_doc_*.
Documento acima de 6 MB
O limite aplica-se ao ficheiro descodificado (6 MB), o mesmo da aplicação e do portal de recolha. Como o base64 acrescenta um terço de sobrecarga de codificação, o corpo do pedido aceita até 9 MB.
A correção. Comprima o documento (um PDF digitalizado a 300 dpi a cores quase sempre desce abaixo do limite em tons de cinzento) em vez de o dividir.
Fonte de triagem indisponível
Nenhuma das entidades do processo pôde ser confrontada com as listas: a fonte (índice de listas oficiais ou fornecedor) não respondeu. A API recusa-se a concluir — um relatório «limpo» assente numa fonte morta seria o pior falso negativo possível. A falha fica registada no processo (erreurSource). Uma indisponibilidade parcial não produz este 502: a resposta 200 conserva as correspondências das entidades que responderam e nomeia as que falharam em erreurSourceEntites.
A correção. Repita a mesma chamada mais tarde, com a mesma Idempotency-Key: só as respostas de sucesso são memorizadas pela idempotência — repetir depois de um erro executa uma triagem real.
Esta página evoluirá com a API; as âncoras existentes, porém, nunca mudam de endereço — pode guardá-las nos seus registos de operações.