Erros

Toda resposta de erro explica o que aconteceu, a provável causa, como corrigir e onde ler mais:

json

{
  "error": {
    "code": "SIGNING_SESSION_EXPIRED",
    "message": "A sessão de assinatura expirou.",
    "cause": "O prazo do link ou do envelope terminou.",
    "hint": "Solicite um novo link ao remetente.",
    "docs": "https://docs.assinapi.com.br/errors#signing-link",
    "requestId": "req_7f3a…"
  }
}

Trate pelo code (estável). Envie o requestId ao suporte. Stack traces nunca são retornados.

Código	HTTP	O que aconteceu · Provável causa · Como corrigir
VALIDATION_FAILED	422	Os dados enviados são inválidos. Algum campo está ausente, com tipo errado ou fora do formato esperado. → Confira os campos listados em "details" e o schema do endpoint na documentação.
BAD_REQUEST	400	Requisição inválida. O corpo não é um JSON válido ou faltam headers de contexto. → Verifique o formato do corpo (JSON) e os headers enviados.
UNAUTHENTICATED	401	Autenticação necessária. O header Authorization está ausente, malformado ou o token expirou. → Envie "Authorization: Bearer <ASSINAPI_SECRET_KEY>" ou faça login no dashboard.
INVALID_CREDENTIALS	401	E-mail ou senha inválidos. As credenciais não conferem. → Confira as credenciais. Após várias tentativas o acesso é temporariamente bloqueado.
INVALID_API_KEY	401	API Key inválida, revogada ou expirada. A chave foi digitada errada, revogada, expirou ou pertence a um projeto arquivado. → Gere uma nova chave em Dashboard → API Keys e atualize a variável ASSINAPI_SECRET_KEY no seu servidor.
SESSION_EXPIRED	401	Sua sessão expirou. O access token expirou ou a sessão foi encerrada. → Faça login novamente.
REFRESH_TOKEN_REUSED	401	Refresh token reutilizado. A sessão foi revogada por segurança. Um refresh token antigo foi usado novamente — possível vazamento. → Faça login novamente. Se não foi você, troque sua senha.
FORBIDDEN	403	Você não tem permissão para esta ação. Seu papel na organização não inclui esta permissão, ou a rota é exclusiva do dashboard. → Peça a um OWNER ou ADMIN da organização para ajustar seu papel.
INSUFFICIENT_SCOPE	403	A API Key não possui o escopo necessário. A chave foi criada com escopos restritos. → Crie uma chave com o escopo indicado em "details.requiredScope".
ENVIRONMENT_MISMATCH	403	Credencial de outro ambiente. Uma chave de Produção foi usada no endpoint de Sandbox (ou vice-versa). → Chaves ask_test_ usam sandbox.api.assinapi.com.br; chaves ask_live_ usam api.assinapi.com.br.
NOT_FOUND	404	Recurso não encontrado. O ID não existe, pertence a outro projeto ou ao outro ambiente (Sandbox/Produção). → Confira o ID, o projeto e o ambiente da credencial usada.
CONFLICT	409	Conflito com o estado atual do recurso. O recurso foi alterado por outra requisição ou já existe. → Recarregue o recurso e tente novamente.
EMAIL_ALREADY_REGISTERED	409	Não foi possível concluir o cadastro. Pode já existir uma conta com estes dados. → Se você já possui conta, faça login ou recupere a senha.
SLUG_TAKEN	409	Identificador já utilizado. Outro recurso da organização usa o mesmo slug. → Escolha outro slug.
IDEMPOTENCY_KEY_REUSED	422	Idempotency-Key já usada com outro corpo de requisição. A mesma chave foi reaproveitada para uma operação diferente. → Gere uma nova Idempotency-Key (UUID) para cada operação distinta.
IDEMPOTENCY_IN_PROGRESS	409	Uma requisição com esta Idempotency-Key ainda está em processamento. Um retry chegou antes da requisição original terminar. → Aguarde alguns segundos e repita a mesma requisição.
RATE_LIMITED	429	Muitas requisições. O limite por minuto deste endpoint foi atingido. → Aguarde o tempo indicado no header Retry-After e aplique backoff exponencial.
PAYLOAD_TOO_LARGE	413	Arquivo maior que o permitido. O PDF excede o tamanho máximo do plano. → Envie PDFs de até 20 MB (limite configurável por plano).
UNSUPPORTED_MEDIA_TYPE	415	Tipo de arquivo não suportado. O arquivo não é um PDF, está corrompido ou protegido por senha. → Envie um PDF válido e sem senha (o conteúdo deve começar com %PDF-).
MALWARE_DETECTED	422	O arquivo foi bloqueado pela verificação de segurança. O antivírus identificou conteúdo malicioso no arquivo. → Gere o PDF novamente a partir da fonte original.
DOCUMENT_LOCKED	409	Esta versão do documento já foi enviada para assinatura e não pode ser alterada. Documentos enviados tornam-se imutáveis para preservar a integridade. → Crie uma nova versão do documento.
INVALID_STATE_TRANSITION	409	Operação não permitida no status atual do envelope. O envelope já avançou (ex.: foi enviado, concluído ou cancelado). → Consulte "details.from" e a máquina de estados na documentação.
ENVELOPE_NOT_EDITABLE	409	O envelope já foi enviado e não pode ser editado. Após o envio, documentos e signatários ficam congelados. → Cancele e crie um novo envelope.
ENVELOPE_INCOMPLETE	422	O envelope precisa de ao menos um documento e um signatário. O envio foi solicitado antes de anexar documento ou signatário. → Adicione documentos (POST /v1/envelopes/:id/documents) e signatários (POST /v1/envelopes/:id/signers).
QUALIFIED_PROVIDER_UNAVAILABLE	422	Assinatura qualificada ICP-Brasil exige um provedor configurado. Nenhum PSC ICP-Brasil está integrado para este ambiente. → Use signatureLevel ADVANCED ou configure um QualifiedSignatureProvider.
CPF_REQUIRED	422	CPF obrigatório para assinatura avançada. A assinatura avançada (padrão) confere o CPF antes do envio do código. → Informe o CPF do signatário ou use signatureLevel SIMPLE.
INVALID_CPF	422	CPF inválido. Os dígitos verificadores não conferem. → Confira o número. No Sandbox use os CPFs de teste da documentação.
PHONE_REQUIRED	422	Telefone obrigatório para OTP por SMS. O signatário usa SMS_OTP mas não tem telefone cadastrado. → Informe phone no formato E.164 (+5511999999999) ou use EMAIL_OTP.
SIGNING_TOKEN_INVALID	404	Link de assinatura inválido. O link está incompleto ou não existe. → Solicite um novo link ao remetente.
SIGNING_SESSION_EXPIRED	410	A sessão de assinatura expirou. O prazo do link ou do envelope terminou. → Solicite um novo link ao remetente.
SIGNING_SESSION_REVOKED	410	Este link foi revogado. Um novo link foi gerado para este signatário ou o envelope foi encerrado. → Use o link mais recente ou solicite um novo ao remetente.
ENVELOPE_NOT_SIGNABLE	409	Este documento não está disponível para assinatura. O envelope foi concluído, cancelado, recusado ou expirou. → Fale com o remetente se precisar assinar novamente.
NOT_YOUR_TURN	409	Aguarde os signatários anteriores. O envelope usa ordem de assinatura e ainda não é a vez deste signatário. → Você será notificado quando for sua vez.
IDENTITY_MISMATCH	422	Os dados de identificação não conferem. O CPF informado é diferente do cadastrado pelo remetente. → Confira o CPF informado.
OTP_COOLDOWN	429	Aguarde antes de solicitar um novo código. Um código foi enviado há poucos segundos. → Tente novamente após "details.retryAfterSeconds" segundos.
OTP_LIMIT_REACHED	429	Limite de códigos atingido. Foram solicitados muitos códigos ou houve muitas falhas de identificação na última hora. → Aguarde uma hora ou solicite um novo link ao remetente.
OTP_INVALID	422	Código incorreto. O código digitado não corresponde ao enviado. → Confira o código recebido. "details.attemptsRemaining" indica as tentativas restantes.
OTP_EXPIRED	410	O código expirou. Códigos valem por 5 minutos. → Solicite um novo código.
OTP_LOCKED	429	Número máximo de tentativas excedido. O código foi digitado incorretamente várias vezes e foi bloqueado. → Solicite um novo código.
OTP_NOT_REQUESTED	422	Nenhum código ativo. O código ainda não foi solicitado, já foi usado ou foi bloqueado. → Solicite um código primeiro.
DOCUMENT_NOT_VIEWED	422	Visualize o documento antes de assinar. A assinatura exige evidência de acesso ao conteúdo. → Abra o documento no portal; a visualização é registrada como evidência.
AUTHENTICATION_REQUIRED	403	Confirme sua identidade antes de assinar. O código OTP não foi validado ou a validação tem mais de 30 minutos. → Valide o código OTP enviado.
CONSENT_REQUIRED	422	É necessário aceitar expressamente a declaração de consentimento. O campo accepted não foi enviado como true. → Envie accepted=true e o consentHash recebido em POST /consent.
CONSENT_MISMATCH	409	O texto de consentimento mudou. O hash enviado não corresponde à declaração atual do envelope. → Solicite novamente a declaração (POST /consent) e confirme.
DOCUMENT_HASH_MISMATCH	409	O documento apresentado difere do documento registrado. O arquivo foi alterado ou o navegador enviou um hash desatualizado. → Recarregue a página e revise o documento antes de assinar.
ALREADY_SIGNED	409	Este signatário já assinou. A assinatura já foi registrada (possivelmente por um retry). → Nenhuma ação necessária.
EVIDENCE_NOT_READY	409	As evidências ainda estão sendo geradas. O envelope foi concluído há instantes e os artefatos estão em processamento. → Tente novamente em alguns segundos ou aguarde o webhook envelope.completed.
WEBHOOK_URL_NOT_ALLOWED	422	URL de webhook não permitida. A URL não usa HTTPS, não resolve no DNS ou aponta para uma rede privada. → Use uma URL https pública; para testar localmente use `assinapi listen`.
SANDBOX_ONLY	403	Operação disponível apenas no Sandbox. Uma credencial de Produção foi usada em um recurso de testes. → Use uma chave ask_test_.
DOCUMENT_LIMIT_REACHED	402	Limite mensal de documentos atingido. A franquia do plano foi consumida e os excedentes estão bloqueados. → Faça upgrade do plano ou habilite excedentes em Uso e cobrança. O Sandbox continua disponível.
PLAN_LIMIT_REACHED	403	Recurso além do limite do plano. O plano atual não permite criar mais itens deste tipo. → Faça upgrade do plano. Nenhum dado existente foi alterado.
PLAN_CHANGE_NOT_ALLOWED	409	Mudança de plano não permitida. O plano solicitado não está disponível para contratação direta ou é igual ao atual. → Para Enterprise, fale com vendas.
OVERAGE_NOT_AVAILABLE	422	Excedente indisponível neste plano. O plano Free não permite excedentes. → Faça upgrade para um plano pago para habilitar excedentes.
PAYMENT_PROVIDER_UNAVAILABLE	503	Pagamento indisponível. Nenhum provedor de pagamento está configurado neste ambiente. → Fale com o suporte para contratar um plano pago.
PROVIDER_ERROR	502	Falha em provedor externo. O serviço de e-mail, SMS ou ICP-Brasil não respondeu corretamente. → Tente novamente; o problema foi registrado.
INTERNAL_ERROR	500	Erro interno. Uma falha inesperada ocorreu na AssinAPI. → Tente novamente. Se persistir, envie o requestId ao suporte.
SERVICE_UNAVAILABLE	503	Serviço indisponível. Uma dependência está temporariamente fora do ar. → Tente novamente em instantes.