Skip to content
Ravisign
PT EN ES
Sign in Create account

Error format

Every API error uses the real HTTP status and the same body format, so that your system can handle failures in a single way.

JSON
{
    "ok": false,
    "erro": {
        "codigo": "signatario_invalido",
        "mensagem": "Há um signatário com dados inválidos.",
        "campo": "signatarios.0.email"
    }
}
Field Description
codigo Stable. Use it in your system's logic
mensagem Comes in the account language (Portuguese, English or Spanish) and can be shown to the user; the text may change over time
campo Appears when the error concerns a parameter. For signers, it points to the position in the list (starting at 0) and the field, such as signatarios.1.email. For template variables, variaveis.<chave>

Tip never compare the text of mensagem in your code. Compare codigo, which does not change.

Codes by HTTP status#

HTTP When Codes
400 Missing or invalid parameter 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 (in the signer registration), nivel_indisponivel, documento_invalido, documento_protegido (password-protected PDF), modelo_variavel_faltando, motivo_obrigatorio, webhook_url_invalida, webhook_eventos_invalidos
401 No key, or key invalid, revoked or deactivated nao_autenticado, chave_invalida
402 Plan's monthly envelope limit reached plano_limite
403 Account blocked or canceled, trial expired, no plan, insufficient scope conta_inativa, conta_teste_vencido, plano_invalido, escopo_insuficiente
404 Route or resource does not exist (or belongs to another account) rota_inexistente, envelope_nao_encontrado, signatario_nao_encontrado, modelo_nao_encontrado, webhook_nao_encontrado
405 Method not accepted by the action (the Allow header says which one applies) metodo_nao_permitido
409 The current status does not allow the action situacao_invalida, envelope_encerrado, envelope_vencido, signatario_fora_da_vez, documento_pendente, arquivo_indisponivel, canal_indisponivel (otp_gerar for a signer on another channel), webhook_limite
413 Document larger than 20 MB documento_grande
429 Rate limit per minute or limit of codes per hour cota_excedida, otp_reenvio_limite
500 Unexpected Ravisign failure erro_interno
501 Action not available yet nao_implementado
503 Temporary unavailability of a Ravisign service; retry in a few minutes pdf_indisponivel, pdf_concatenacao_indisponivel, assinatura_indisponivel, carimbo_nao_configurado, otp_envio_falhou

When to retry a request#

Situation What to do
429 cota_excedida Wait the number of seconds in the Retry-After header and retry
429 otp_reenvio_limite The limit of 4 codes per hour is released over the following hour. Use the code already generated, which signatarios/otp_pendente returns
500 and 503 Retry later, with increasing waits between attempts (for example 1, 5 and 15 minutes)
Network failure with no response Before creating it again, search for the envelope by referencia_externa in envelopes/listar to avoid creating a duplicate
Other 4xx They are not solved by retrying: fix the parameter or the status indicated

Handling example#

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
    }
}
Did not find what you were looking for?

Contact Ravi Systems support at the e-mail below.

contato@ravisystems.com.br