Erros e limites

Códigos de resposta

Código	Quando acontece	O que fazer
202	Documento aceito e em processamento.	Guarde o id.
200	Repetição de um envio idempotente.	Nada — é o mesmo documento.
401	Chave ausente, inválida, revogada ou expirada.	Verifique a chave; emita outra se necessário.
402	Licença fora de vigência ou quota esgotada.	Fale com o time SignXP. Não repita a chamada em loop.
403	Cliente inativo.	Fale com o time SignXP.
409	Idempotency-Key reutilizada com conteúdo diferente, external_id já usado, ou cancelamento de um documento que já foi encerrado.	Confira o estado atual do documento antes de repetir.
422	Payload inválido.	Corrija conforme o corpo do erro.
429	Limite de requisições por minuto excedido.	Respeite o Retry-After e reduza a frequência.

Erros de validação seguem o formato padrão do Laravel:

{
  "message": "O campo title é obrigatório.",
  "errors": {
    "title": ["O campo title é obrigatório."]
  }
}

Quota mensal

A quota é contada em documentos enviados e aceitos, por mês. O período reinicia no dia 1º.

Nas respostas de envio bem-sucedidas devolvemos:

X-Quota-Limit: 500
X-Quota-Remaining: 361

Quando a quota se esgota, novos envios recebem 402:

{
  "message": "Quota mensal de 500 documentos esgotada.",
  "quota": { "limit": 500, "used": 500, "period": "2026-07" }
}

Assinaturas em andamento não são afetadas: os links continuam válidos, os documentos são selados normalmente e a consulta de status segue respondendo. Apenas o envio de documentos novos é bloqueado.

Envios com chave sk_test_ não consomem quota.

Cancelar um documento não devolve a quota. O consumo é contado no envio, no período do envio, e não volta — devolver creditaria o mês errado e faria o ciclo enviar/cancelar disparar convites sem limite. O cancelamento continua permitido com a quota esgotada, porém: derrubar um link pendente é o que você mais precisa poder fazer nessa situação.

Acompanhe o consumo em tempo real em Consumo, no portal da sua conta.

Limite de requisições

Cada licença tem um teto de requisições por minuto (padrão: 60). Ao ultrapassá-lo, a API responde 429 com o cabeçalho Retry-After.

Boas práticas:

• prefira callbacks a polling;
• se precisar de polling, espace as consultas e use backoff exponencial nos erros;
• não paralelize envios em massa sem controle de concorrência.

Recursos da licença

Alguns recursos são contratados à parte. Se a sua licença não os inclui, o envio que tentar usá-los recebe 422:

Recurso	O que fica indisponível
Coleta de evidências	evidence.document e evidence.selfie.
Rúbrica e ordem de assinatura	Campos INITIALS e signing_order.
Validação por IA	Conferência automática de documento e selfie durante a assinatura, e a conferência de tax_id contra o documento fotografado. Veja validação por IA.
Verificação pública	Página /validar, o validador público, os endpoints /api/verify/... e o download da cópia certificada.

A seção Chaves de API mostra quais recursos estão liberados na sua licença, e GET /api/v1/license devolve os mesmos dados para o seu código (veja Autenticação).