Cada erro, explicado num endereço estável.

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.

O mesmo 401 traz "motif": "fin_option_api" quando a chave foi parada porque a API deixou de fazer parte da subscrição do gabinete. A data dessa paragem foi indicada num e-mail aos administradores do gabinete ou, na falta destes, ao endereço de faturação do gabinete, e depois anunciada no cabeçalho Sunset de cada resposta a uma chamada aceite (calendário em #cle-expiree). Sem motivo, pode também resultar de uma subscrição suspensa: a suspensão corta as chaves de imediato.

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. Com "motif": "fin_option_api", nem o cabeçalho nem a chave estão em causa: o administrador do gabinete escreve-nos para contact@vigilae.org para que a API volte à subscrição, e a mesma chave volta a ser aceite logo que isso aconteça, até ao seu próprio prazo de validade.

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.

Uma chave API pode também deixar de ser aceite antes dessa data, quando a API deixa de fazer parte da subscrição do gabinete. A paragem ocorre então pelo menos 30 dias depois de um primeiro e-mail, na data indicada por um segundo e-mail, enviado pelo menos 7 dias antes; ambos seguem para os administradores do gabinete ou, na falta destes, para o endereço de faturação do gabinete. Logo que fixada, essa data pode ler-se na consola do gabinete (campo coupure_le de GET /connect/cles), e cada resposta a uma chamada aceite anuncia-a no cabeçalho Sunset até que chegue. Passada essa data, a chamada recebe o 401 descrito em #authentification, com "motif": "fin_option_api"; se a API voltar à subscrição, a chave volta a ser aceite, até ao seu próprio prazo de validade.

A correção. Crie uma chave nova, mude as suas chamadas para ela, revogue a antiga. Para uma chave API, é preciso que a API ainda faça parte da subscrição do gabinete: sem ela, a consola recusa criar uma. Planeie esta substituição nas suas operações em vez de a descobrir.

Scope insuficiente

As chaves transportam os scopes assinalados na sua criação: os gerais lecture (leitura, por defeito) e ecriture (escrita), ou os finos por recurso (clients:lecture, pieces:ecriture, origine-fonds:lecture, journal:lecture…).

A herança segue o sufixo, num só sentido: lecture cobre todos os *:lecture, ecriture todos os *:ecriture — nunca ao contrário; um scope fino abre apenas a si próprio.

Seis scopes saem deste par e não se herdam de nenhuma chave geral: alertes:qualifier, embed:emettre, adversemedia:consulter, conformite:consulter, dispositif:consulter, integrite:consulter. Qualificar um evento, emitir um token de incorporação, ler a imprensa desfavorável de um processo ou uma nota de condução do processo nunca decorre de um direito de leitura geral: cada um assinala-se à parte.

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, e uma chave ampla nunca compensa um scope que não foi delegado de forma explícita.

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.

Esta conta já existe

Um POST /scim/v2/Users sobre um userName já aprovisionado para este gabinete responde 409 com scimType: uniqueness. A unicidade é assegurada por uma restrição de base de dados, não por uma cache: duas criações simultâneas não podem produzir duas contas.

A correção. Trate o 409 como um sucesso idempotente, não como um erro: releia a conta com ?filter=userName eq "…" e prossiga com o identificador devolvido. Um conector que repete em ciclo perante um 409 nunca criará mais nada.

Esta conta está fora do alcance do diretório

Um diretório não pode despromover nem desativar uma conta que detém poderes de administração do gabinete: o pedido é recusado com scimType: mutability e registado. Sem esse limite, um conector que adote o endereço do responsável pelo cumprimento fecharia o gabinete a quem responde por ele.

A correção. Retire essa pessoa do perímetro sincronizado, ou altere o seu papel a partir do Vigilae. A recusa abrange apenas esta conta: o resto do lote é aplicado normalmente.

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.

Campo cujo valor é demasiado longo: Nacionalidade

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.

Outra tentativa com esta chave ainda está em curso

Dois pedidos com a mesma Idempotency-Key chegaram juntos: o primeiro executa-se, o segundo é recusado antes de qualquer efeito. É essa recusa que impede o duplicado. O caso corrente: um proxy devolve 502 ou 504 enquanto o servidor ainda trabalha, e o seu cliente repete o pedido. O cabeçalho Retry-After diz ao fim de quantos segundos repetir.

A correção. Repita o mesmo pedido, tal como está, com a mesma chave, passado o prazo anunciado: receberá a resposta da primeira tentativa. Nunca fabrique uma chave nova para «desbloquear» — seria criar o duplicado que a chave evita.

Ambiente de teste: quota atingida

Um ambiente de teste mantém limites fixos: 200 fichas de cliente, 50 processos e 40 documentos por processo. Uma criação ou uma submissão que ultrapasse um deles é recusada antes de qualquer escrita, e a recusa diz qual: os campos ressource, quota e courant indicam o recurso, o teto e o total no momento da recusa. De duas criações simultâneas pela última vaga, só uma passa. Editar uma ficha ou um processo existente não consome nada.

A correção. Estas quotas não se negociam, e repetir o pedido devolverá a mesma recusa. Reponha o ambiente de teste a partir do seu espaço — recomeça a partir dos dados de demonstração — ou contrate uma subscrição: estas quotas só se aplicam aos ambientes de teste.

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.

Processo encerrado: a relação de negócio terminou

A relação foi encerrada na aplicação: o processo já não recebe escritas pela API — nem edição, nem documento, nem triagem, nem beneficiários efetivos. As leituras continuam abertas: um processo encerrado consulta-se e exporta-se durante todo o prazo de conservação.

A correção. Reabrir a relação é um ato humano e registado, na aplicação; a API não o faz por si. Se a operação é nova, abra um processo novo em vez de reanimar o antigo.

Processo expurgado: os dados foram apagados

O prazo de conservação terminou e os dados do processo foram apagados. Resta apenas o rasto de auditoria, que atesta que um processo existiu e que foi expurgado na data indicada; já não recebe qualquer escrita.

A correção. Nada a corrigir e nada a repetir: o apagamento é definitivo e deliberado. Um identificador de processo expurgado guardado nos seus sistemas é um histórico, nunca um destino de escrita.

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.

Widgets integrados não ativados nesta instância

O mint POST /api/v1/embed/jetons depende das origens declaradas do seu gabinete — é essa lista que pilota a CSP frame-ancestors do shell integrado. Este 501 diz que a instância chamada não tem esse armazenamento: a superfície de embed está ali inerte por construção, e di-lo em vez de emitir um token que nenhuma origem poderia alguma vez mostrar. Não confundir com o 400 devolvido a um gabinete cujas origens ainda não estão declaradas.

A correção. Este 501 fala da instância, não do seu pedido. Em vigilae.org, o administrador do seu gabinete declara as origens ele próprio, no ecrã «Integrações e segurança» (a caixa da secção de widgets diz onde); depois repita a mesma chamada. Nada a mudar no seu código: o pedido estava correto, a instância não estava pronta.

Superfície indisponível nesta instância

Duas leituras de base — GET /api/v1/dossiers/{id}/origine-fonds e GET /api/v1/dossiers/{id}/exigences — apoiam-se em armazenamentos que nem todas as instâncias possuem. Quando falta um, a API di-lo em vez de servir uma lista vazia: «nada a assinalar» e «nada foi lido» são factos opostos, e confundi-los faria passar um processo que ninguém consultou por um processo sem reservas. Este 501 fala da instância chamada, nunca do seu pedido nem do processo.

A correção. Não repita o pedido em ciclo: nada mudará enquanto a instância não possuir esse armazenamento. Trate este código como «dado indisponível aqui» e sobretudo não o conte como um zero nos seus painéis — é assim que uma medição ausente se torna um número errado. Em vigilae.org ambas as leituras são servidas; num alojamento dedicado, a atualização do armazenamento cabe ao seu operador.