ShieldSign PKIDocumentação
Documentação / Referência

Erros

O formato das respostas de erro e todos os códigos estáveis.

O formato#

Toda resposta de erro tem o mesmo formato, inclusive as de corpo grande demais, JSON inválido, método não permitido e endereço inexistente:

{ "error": { "code": "certificate_not_trusted", "message": "…", "reason": "chain" } }
Campo O que é
code Código estável. Programe contra ele, nunca contra a mensagem.
message Texto em português, para registro e depuração. Pode mudar.
reason Subcódigo opcional, só nas recusas de certificado (lista).

Toda resposta traz o cabeçalho X-Request-Id. Registre-o junto do erro e informe-o ao pedir suporte.

Os erros 429 (e alguns 409) trazem Retry-After, em segundos.

Todos os códigos#

HTTP / code Significa O que fazer
400 e 422 invalid_request Corpo ou campos inválidos (JSON quebrado, campo obrigatório ausente), arquivo que não é PDF, lote grande demais. Corrigir a chamada e mostrar a mensagem.
401 unauthorized Chave de API ausente, errada ou revogada. Problema seu: alerta interno, não do usuário.
403 quota_exceeded A cota mensal do plano acabou (ou o lote não cabe no que resta). Avisar o comercial.
403 tenant_suspended O cliente está suspenso. Fale com o suporte.
404 token_not_found Sessão expirada (15 min), de outro cliente ou já concluída. Reiniciar a assinatura.
404 not_found Endereço que a API não tem. Corrigir a chamada.
405 method_not_allowed Método não permitido para o endereço (inclusive o OPTIONS: a API não atende o navegador). Corrigir a chamada.
408 upload_timeout O envio demorou mais que o permitido (10 minutos) e foi cancelado. Enviar de novo por uma conexão melhor ou em lotes menores.
409 invalid_session_state Passo fora de ordem (por exemplo, complete antes do prepare), ou chave de idempotência diferente numa sessão concluída. Reiniciar.
409 complete_in_progress A conclusão desta sessão ainda está em andamento (por exemplo, carimbo de tempo lento). Esperar e repetir com a mesma Idempotency-Key.
409 signature_field_exists O PDF já tem um campo com o signatureFieldName pedido. Escolher outro nome (Vários signatários).
413 payload_too_large PDF ou corpo acima do limite. Reduzir, ou usar o envio multipart (limites).
415 unsupported_media_type Content-Type errado. Enviar application/json (ou multipart/form-data no envio de arquivos).
400 invalid_visual_representation Assinatura visível inválida (página, retângulo fora da página, texto que não cabe, imagem…). Corrigir e chamar o prepare de novo: a sessão continua aberta.
422 certificate_not_trusted Cadeia do certificado inválida (veja o reason). O usuário usar outro certificado.
422 certificate_revoked AD-RC e AD-RA: o certificado foi revogado. Trocar de certificado.
422 revocation_unavailable Não foi possível consultar a revogação. Tentar de novo.
422 certificate_issuer_not_allowed O certificado não é de uma AC listada em acceptableIssuers. O usuário usar outro certificado.
422 certificate_key_not_supported Login por certificado com chave EC de até 256 bits (P-256). O usuário usar outro certificado (Login com certificado).
422 invalid_signature A assinatura não confere com o certificado (ou PIN/dispositivo errado). Repetir o complete com a assinatura certa. No login por certificado, peça um desafio novo.
422 invalid_pdf PDF corrompido, criptografado ou malformado. Pedir outro arquivo.
422 tsa_unavailable O serviço de carimbo de tempo não respondeu. Nada foi assinado. Tentar de novo em instantes.
429 rate_limited Limite de requisições por minuto. Esperar o Retry-After.
429 tenant_storage_limit O cliente tem sessões ou bytes demais em andamento. Concluir ou apagar sessões; esperar o Retry-After.
502 engine_error Falha interna ao processar a assinatura. Tentar de novo; registrar o X-Request-Id.
503 store_unavailable Serviço temporariamente indisponível. Tentar de novo; registrar o X-Request-Id.
507 storage_full Disco temporário do servidor cheio. Tentar mais tarde.

Quais erros repetir#

  • Repita (com espera crescente): falha de rede, 408, 429, 502, 503, 504, 409 complete_in_progress e 422 tsa_unavailable. No complete, sempre com a mesma Idempotency-Key (Sessões).
  • Não repita sem mudar algo: os demais 4xx. São erros de negócio ou de integração, e repetir devolve o mesmo erro.
  • 401 é o seu servidor com a chave errada: trate como incidente seu, e não mostre ao usuário final.

O reason das recusas de certificado#

expired, not_yet_valid, chain, key_usage, revoked, revocation_unavailable, algorithm, malformed, issuer_not_allowed e other. A tabela, com a mensagem sugerida para cada um, está em Identidade do certificado.

ShieldSign PKI · Shield Certificadora · contato@shieldcertificadora.com.br · Privacidade