Erros comuns
Tabela de diagnóstico dos erros de integração com a API e os webhooks da KivoSign.
Este guia reúne os códigos de erro padrão retornados pela API da KivoSign. Use-o para diagnosticar e resolver problemas de integração com envelopes, destinatários e webhooks.
Códigos de erro da aplicação
| Código | Descrição | Ação recomendada |
|---|---|---|
ALREADY_EXISTS | O recurso que você está tentando criar já existe. | Confira se a entidade (ex.: usuário, envelope, webhook) já foi criada. Use uma requisição de atualização em vez de criação. |
EXPIRED_CODE | O código de acesso ou token informado expirou. | Gere um novo código de acesso ou peça um novo link de convite antes de tentar de novo. |
INVALID_BODY | O payload da requisição está malformado. | Revise a estrutura do JSON. Ele deve seguir exatamente o schema esperado, sem campos obrigatórios faltando. |
INVALID_REQUEST | A requisição como um todo está malformada ou inválida. | Revise os parâmetros da chamada: URL, query string e cabeçalhos. Corrija a sintaxe da requisição. |
RECIPIENT_EXPIRED | O link de assinatura ou o acesso do destinatário expirou. | Gere e reenvie um novo convite ao destinatário. |
LIMIT_EXCEEDED | A cota de uso da sua conta foi excedida. | Confira os limites do seu plano. Faça upgrade ou aguarde a renovação do ciclo de cobrança. |
MISSING_ENV_VAR | Falta uma configuração obrigatória no servidor (500). | Fale com o suporte. |
MISSING_SIGNATURE_FIELD | Um signatário está sem campo de assinatura no documento (400). Retornado ao distribuir um envelope. | Adicione pelo menos um campo de assinatura para cada destinatário com papel de assinatura antes de chamar /envelope/distribute. |
NOT_FOUND | O recurso solicitado não foi encontrado (404). | Confira o ID do recurso (envelope, documento, webhook) informado na URL e se ele não foi excluído. |
NOT_IMPLEMENTED | O recurso solicitado não é suportado pelo servidor no momento. | Consulte a documentação da API para ver os métodos disponíveis. Não use este endpoint por enquanto. |
NOT_SETUP | A configuração necessária para esta ação está incompleta. | Acesse as configurações da conta ou da integração e conclua a configuração antes de tentar de novo. |
INVALID_CAPTCHA | A validação do token de segurança (Captcha) falhou. | Confira se o token do Captcha é gerado corretamente no cliente e enviado sem alterações. |
UNAUTHORIZED | Autenticação ausente ou inválida (401). | Confira se a chave de API está correta, ativa e enviada no cabeçalho Authorization. |
FORBIDDEN | Acesso ao recurso negado (403). | Confira se a chave de API ou o usuário tem as permissões e papéis necessários para a ação. |
UNKNOWN_ERROR | Ocorreu um erro interno inesperado (500). | Tente de novo mais tarde. Se persistir, fale com o suporte informando o payload e o horário do ocorrido. |
RETRY_EXCEPTION | A operação falhou temporariamente, mas pode ser repetida. | Implemente novas tentativas automáticas na integração, de preferência com backoff exponencial. |
SCHEMA_FAILED | A validação estrita do schema falhou. | Confira se os tipos enviados (string, número, booleano) batem exatamente com a especificação OpenAPI. |
TOO_MANY_REQUESTS | Limite de requisições excedido (429). | Diminua a frequência das chamadas. Trate o limite com base nos cabeçalhos da resposta. |
TWO_FACTOR_AUTH_FAILED | A autenticação em dois fatores (2FA) falhou. | Confira o código 2FA informado, se foi digitado corretamente e se não expirou. |
WEBHOOK_INVALID_REQUEST | A requisição relacionada ao webhook é inválida. | Confira a configuração do endpoint receptor: a URL deve estar correta e o servidor deve aceitar requisições POST da KivoSign. |
Erros de estado do envelope
Estes erros acontecem ao tentar uma ação incompatível com o estado atual do envelope.
| Código | Descrição | Ação recomendada |
|---|---|---|
ENVELOPE_DRAFT | A ação não pode ser feita porque o envelope ainda é um rascunho. | Conclua a configuração do envelope e envie-o (estado PENDING) antes desta operação. |
ENVELOPE_COMPLETED | A ação não pode ser feita porque o envelope já foi concluído. | Depois de concluída a assinatura, o envelope não aceita mais alterações (ex.: incluir signatários, alterar documentos). |
ENVELOPE_REJECTED | A ação não pode ser feita porque um destinatário recusou o envelope. | O fluxo de assinatura foi encerrado de vez. Crie um novo envelope se quiser reenviar o documento. |
ENVELOPE_CANCELLED | A ação não pode ser feita porque o envelope foi cancelado (400). | Crie um novo envelope se precisar reiniciar o processo de assinatura. |
ENVELOPE_LEGACY | A ação não pode ser feita porque o envelope usa um formato antigo. | O envelope foi criado em uma versão antiga do sistema. Recrie-o com a versão atual da API para interagir com ele. |
ENVELOPE_TSP_LOCKED | Um envelope AES/QES não pode ser alterado depois de sair do rascunho (400). | Faça as alterações enquanto o envelope está em DRAFT ou crie um novo envelope. |
Erros de assinatura CSC
Estes erros se aplicam aos fluxos de assinatura via Cloud Signature Consortium (CSC).
| Código | Descrição | Ação recomendada |
|---|---|---|
CSC_INSTANCE_MODE_MISMATCH | O nível de assinatura pedido não corresponde ao modo CSC configurado (400). | Use o nível de assinatura suportado pela configuração de assinatura. |
CSC_UNLICENSED | A assinatura CSC não está habilitada (403). | Fale com o suporte para habilitar a assinatura CSC. |
CSC_PROVIDER_INFO_FAILED | A consulta de descoberta ao provedor CSC falhou ou retornou dados inutilizáveis (500). | Tente de novo. Se persistir, fale com o suporte. |
CSC_PROVIDER_NO_TSA | A autoridade de carimbo do tempo está indisponível ou inutilizável para a assinatura CSC (500). | Tente de novo. Se persistir, fale com o suporte. |
CSC_CREDENTIAL_LIST_EMPTY | O provedor CSC não retornou credenciais de assinatura para o usuário autenticado (400). | Cadastre uma credencial de assinatura no provedor e autentique de novo. |
CSC_CERT_INVALID | O certificado escolhido está ausente, inválido ou fora da validade (400). | Escolha ou renove um certificado válido e autentique de novo. |
CSC_ALGORITHM_REFUSED | A credencial usa um algoritmo de chave ou de hash não suportado (400). | Escolha uma credencial compatível com a política de algoritmos CSC. |
CSC_SAD_EXPIRED_PRE_SIGN | Os dados de ativação da assinatura estão ausentes, expirados ou ilegíveis antes da assinatura (400). | Repita o fluxo de autorização da credencial. |
CSC_TSP_TIMEOUT | O prestador de serviço de confiança não concluiu a assinatura dentro do prazo (408). | Tente assinar de novo depois de confirmar que o provedor está disponível. |
CSC_EMBED_FAILED | A assinatura CSC retornada não pôde ser incorporada aos itens do envelope (400). | Reinicie a assinatura. Se falhar de novo, fale com o suporte. |
CSC_BASE_DOCUMENT_MUTATED | O documento mudou entre a preparação e a assinatura (500). | Reinicie a assinatura a partir do estado atual do envelope. |
CSC_REQUEST_FAILED | Uma requisição ao provedor CSC falhou sem um erro CSC mais específico (500). | Confira a disponibilidade do provedor e tente de novo. |