Catálogo de erros - SuperSign

Decida pelo status HTTP e por error.code; error.message é destinado ao diagnóstico humano e pode evoluir.

Código	HTTP esperado	Como tratar
`INVALID_API_KEY`	`401`	Confira ambiente, prefixo, revogação e header `Authorization`.
`API_KEY_EXPIRED`	`401`	A chave passou da validade; emita outra e troque na integração.
`API_SCOPE_INSUFFICIENT`	`403`	A chave não tem o escopo de `error.details.requiredScope`; emita outra.
`ACCOUNT_SUSPENDED`	`403`	A conta está suspensa; nenhuma operação é aceita. Fale com o suporte.
`ACCOUNT_SUSPENDED_BILLING`	`403`	Pagamento pendente: só leitura e download seguem; regularize a fatura.
`RESOURCE_NOT_FOUND`	`404`	Confira o identificador, a conta e se o responsável pela chave o vê.
`RATE_LIMIT_EXCEEDED`	`429`	Respeite `Retry-After` e repita com backoff e jitter.
`IDEMPOTENCY_KEY_REQUIRED`	`400`	Envie `Idempotency-Key` em toda operação `POST`.
`IDEMPOTENCY_KEY_IN_USE`	`409`	Aguarde e repita a mesma requisição com a mesma chave.
`IDEMPOTENCY_KEY_REUSE`	`422`	Não reutilize a chave com rota ou corpo diferente.
`IDEMPOTENCY_UNAVAILABLE`	`503`	Repita com backoff sem trocar a chave.
`IDEMPOTENCY_SECRET_NOT_REPLAYABLE`	`409`	O webhook já foi criado; gire o segredo em `.../secret/rotate`.
`ENVELOPE_WRITE_NOT_ALLOWED`	`403`	O envelope não permite essa alteração para o ator ou estado atual.
`VOID_NOT_ALLOWED`	`403`	O usuário responsável pela chave não pode anular este envelope.
`DOCUMENT_TOO_LARGE`	`413`	Reduza o arquivo conforme o limite informado pela resposta.
`VERSION_UNAVAILABLE`	`403`	A versão solicitada do documento não está disponível para download.
`CONTACT_ALREADY_EXISTS`	`409`	Consulte ou atualize o contato existente.
`FOLDER_SELF_MOVE`	`400`	Não mova uma pasta para ela mesma.
`FOLDER_CIRCULAR_MOVE`	`400`	Escolha um destino fora da árvore descendente da pasta.
`NON_EMPTY_FOLDER`	`403`	Remova ou mova o conteúdo antes de excluir a pasta.
`API_APPROVAL_NOT_ENABLED`	`403`	A aprovação pela API não está liberada para a conta; fale com o suporte.
`APPROVER_WAITING_TURN`	`403`	Ainda não é a vez do aprovador; repita quando a etapa anterior concluir.
`DEADLINE_EXPIRED`	`403`	O prazo do envelope venceu; não repita.
`PARTICIPANT_NOT_APPROVER`	`409`	Só participantes com papel de aprovador são aprovados pela API.
`GROUP_APPROVER_NOT_SUPPORTED`	`409`	Aprovador de grupo não é aprovado pela API; o membro aprova pelo link.
`PARTICIPANT_ALREADY_DECLINED`	`409`	O aprovador recusou; não repita.
`ENVELOPE_NOT_APPROVABLE`	`409`	O envelope não está em andamento; veja `error.details.status`.
`INVALID_CPF`	`400`	Confira os dígitos do CPF enviado.
`VALIDATION`	`400`	Confira os campos obrigatórios ou tipos de dados da requisição.
`BAD_REQUEST`	`400`	A requisição está malformada; consulte a mensagem do erro.
`PHONE_NUMBER_REQUIRED`	`400`	Número de telefone obrigatório para este método de autenticação.
`FIELD_PAGE_OUT_OF_BOUNDS`	`400`	Um campo está posicionado em página que não existe no documento.
`PARTICIPANT_DOCUMENT_ACCESS_INVALID`	`400`	`allowedDocumentIds` tem documento que não é do envelope; confira `details.documentIds`.
`FIELD_DOCUMENT_NOT_VISIBLE`	`400`	Campo de participante em documento que ele não vê; libere o documento ou remova o campo.
`FIELD_GEOMETRY_INVALID`	`400`	Campo com coordenada negativa, tamanho zero ou, com `anchor`, que ficaria fora da página; nada foi gravado.
`INVALID_FIELD_LINKING`	`400`	A vinculação entre campos é inválida.
`APPROVAL_ALREADY_PROCESSED`	`400`	O aprovador já processou esta aprovação; não repita.
`CONFLICT`	`409`	Conflito com o estado atual do recurso; consulte a mensagem do erro.
`DOCUMENT_CONVERSION_NOT_PENDING`	`409`	Documento não está esperando confirmação de conversão DOCX.
`ENVELOPE_DOCUMENTS_NOT_READY`	`409`	Envelope tem documento(s) ainda sendo processado; aguarde e tente de novo.
`DOCUMENT_NOT_READY`	`409`	O documento ainda está sendo processado; aguarde e tente de novo.
`ENVELOPE_DOCUMENT_AWAITING_CONFIRMATION`	`409`	Revise e confirme o PDF convertido antes de enviar.
`ENVELOPE_NOT_EDITABLE`	`409`	Envelope já saiu de rascunho/ajuste; não pode mais ser alterado.
`PARTICIPANT_TYPE_CHANGE_NOT_ALLOWED`	`409`	Com o envelope em correção, não troque o tipo nem o grupo de um participante já enviado. Remova esse participante e inclua outro na mesma chamada.
`ENVELOPE_DOCUMENT_NOT_DUPLICABLE`	`409`	Envelope tem documento que não pode ser duplicado (status inválido).
`ENVELOPE_HAS_NO_ORIGINAL_FILE`	`409`	Nenhum documento tem arquivo original armazenado ainda.
`ENVELOPE_HAS_NO_SIGNED_DOCUMENT`	`409`	Envelope não tem documento assinado para baixar.
`WEBHOOK_ENDPOINT_LIMIT_REACHED`	`409`	Conta já tem 20 endpoints de webhook, o máximo; exclua um que não usa.
`ENVELOPE_TAG_LIMIT`	`409`	Envelope já tem 3 etiquetas, o máximo; remova uma antes de aplicar outra.
`TEMPLATE_NOT_DRAFT`	`409`	Só modelos em rascunho podem ser alterados; duplique e altere a cópia.
`CANNOT_EDIT_PARTICIPANT`	`403`	Participante não pode ser editado no estado atual.
`ENVELOPE_SIGNATORIES_LIMIT`	`403`	Envelope atingiu o limite de destinatários do plano.
`ENVELOPES_QUOTA_EXCEEDED`	`403`	Conta atingiu o limite de envelopes; aguarde ou faça upgrade.
`PKI_QUOTA_EXCEEDED`	`403`	A conta atingiu o limite de envelopes com certificado ICP-Brasil do ciclo. O limite renova no próximo ciclo; para ampliar, fale com a SuperSign®.
`SELFIE_QUOTA_EXCEEDED`	`403`	A conta atingiu o limite de envelopes com verificação por selfie do ciclo. O limite renova no próximo ciclo; para ampliar, fale com a SuperSign®.
`PKI_NOT_IN_PLAN`	`403`	Assinatura com ICP-Brasil não está disponível neste plano.
`PKI_CERTIFICATE_CPF_MISMATCH`	`422`	Na assinatura ICP-Brasil, o CPF do certificado não é o `expectedDocumentNumber` do signatário; nada foi gravado. O signatário assina com o certificado do titular, ou quem enviou corrige o CPF esperado.
`API_NOT_IN_PLAN`	`403`	Acesso à API não está disponível neste plano.
`ACCOUNT_HOURLY_VOLUME_LIMIT`	`429`	Conta atingiu o teto de envelopes por hora; aguarde e tente de novo.
`ACCOUNT_MESSAGE_BUDGET_EXCEEDED`	`429`	Orçamento de mensagens da conta foi atingido; aguarde a renovação.
`TEMPLATE_ENVELOPE_MISSING_PARTICIPANTS`	`422`	Vaga do modelo exige nome e contato para enviar; preencha e tente de novo.
`DOCUMENT_HAS_NO_TEXT`	`422`	PDF sem texto legível (escaneado); posicione os campos por coordenadas.
`DOCUMENT_TEXT_UNREADABLE`	`422`	O texto não pôde ser lido nos limites; posicione os campos por coordenadas.
`DOCUMENT_TOO_LARGE_FOR_ANCHOR`	`422`	Arquivo acima do teto da busca por âncora; posicione por coordenadas.
`ANCHOR_SEARCH_BUSY`	`503`	Busca por âncora ocupada; repita após o `Retry-After`.
`ANCHOR_SEARCH_UNAVAILABLE`	`503`	Busca por âncora indisponível no ambiente ou falha temporária; use coordenadas ou repita após o `Retry-After`.
`ANCHOR_NOT_FOUND`	`422`	Texto de `anchor` não achado no `PUT .../fields`; nada foi gravado. `details.anchors` lista TODAS as âncoras não achadas (`fieldId`, `text`). Confira os textos ou use `ifNotFound: "ignore"`.
`ANCHOR_TOO_MANY_MATCHES`	`422`	As âncoras do `PUT .../fields` gerariam mais de 200 campos; use `occurrence` `"first"`/N ou um texto mais específico.

Falhas 5xx, 429, timeout e erros de rede podem ser transitórios. Em operações POST, preserve a mesma Idempotency-Key durante toda a tentativa lógica.