Ir para o conteúdo
Ravisign
PT EN ES
Entrar Criar conta

Formato de erros

Todo erro da API usa o status HTTP real e o mesmo formato de corpo, para que o seu sistema trate as falhas de um jeito só.

JSON
{
    "ok": false,
    "erro": {
        "codigo": "signatario_invalido",
        "mensagem": "Há um signatário com dados inválidos.",
        "campo": "signatarios.0.email"
    }
}
Campo Descrição
codigo Estável. Use-o na lógica do seu sistema
mensagem Vem no idioma da conta (português, inglês ou espanhol) e pode ser mostrada ao usuário; o texto pode mudar com o tempo
campo Aparece quando o erro é de um parâmetro. Em signatários, aponta a posição na lista (a partir de 0) e o campo, como signatarios.1.email. Em variáveis de modelo, variaveis.<chave>

Dica nunca compare o texto de mensagem no seu código. Compare codigo, que não muda.

Códigos por status HTTP#

HTTP Quando Códigos
400 Parâmetro ausente ou inválido parametro_obrigatorio, parametro_invalido, data_invalida, json_invalido, titulo_obrigatorio, valor_invalido, prazo_invalido, signatarios_obrigatorio, signatario_invalido, signatario_email_obrigatorio, cpf_cnpj_invalido, papel_invalido, canal_indisponivel (no cadastro do signatário), nivel_indisponivel, documento_invalido, documento_protegido (PDF com senha), modelo_variavel_faltando, motivo_obrigatorio, webhook_url_invalida, webhook_eventos_invalidos
401 Sem chave, chave inválida, revogada ou desativada nao_autenticado, chave_invalida
402 Limite de envelopes do plano no mês atingido plano_limite
403 Conta bloqueada ou cancelada, teste vencido, sem plano, escopo insuficiente conta_inativa, conta_teste_vencido, plano_invalido, escopo_insuficiente
404 Rota ou recurso inexistente (ou de outra conta) rota_inexistente, envelope_nao_encontrado, signatario_nao_encontrado, modelo_nao_encontrado, webhook_nao_encontrado
405 Método não aceito pela ação (o cabeçalho Allow diz qual vale) metodo_nao_permitido
409 A situação atual não permite a ação situacao_invalida, envelope_encerrado, envelope_vencido, signatario_fora_da_vez, documento_pendente, arquivo_indisponivel, canal_indisponivel (otp_gerar para signatário de outro canal), webhook_limite
413 Documento acima de 20 MB documento_grande
429 Cota por minuto ou limite de códigos por hora cota_excedida, otp_reenvio_limite
500 Falha inesperada do Ravisign erro_interno
501 Ação ainda não disponível nao_implementado
503 Indisponibilidade temporária de um serviço do Ravisign; repita em alguns minutos pdf_indisponivel, pdf_concatenacao_indisponivel, assinatura_indisponivel, carimbo_nao_configurado, otp_envio_falhou

Quando repetir uma requisição#

Situação O que fazer
429 cota_excedida Espere os segundos do cabeçalho Retry-After e repita
429 otp_reenvio_limite O limite de 4 códigos por hora libera ao longo da hora seguinte. Use o código já gerado, que signatarios/otp_pendente devolve
500 e 503 Repita mais tarde, com espera crescente entre as tentativas (por exemplo 1, 5 e 15 minutos)
Falha de rede sem resposta Antes de criar de novo, procure o envelope por referencia_externa em envelopes/listar para não criar um duplicado
Demais 4xx Não se resolvem repetindo: corrija o parâmetro ou a situação indicada

Exemplo de tratamento#

PHP
<?php
$resposta = json_decode($corpo, true);
if (($resposta['ok'] ?? false) !== true) {
    $erro = $resposta['erro'] ?? [];
    switch ($erro['codigo'] ?? '') {
        case 'plano_limite':
            // avisar o administrador: o limite de envelopes do mês acabou
            break;
        case 'cota_excedida':
            // reagendar depois do Retry-After
            break;
        default:
            // registrar codigo, campo e mensagem para análise
    }
}
Não encontrou o que procurava?

Fale com o suporte da Ravi Systems pelo e-mail abaixo.

contato@ravisystems.com.br