Códigos de erro da API ID ZapSign e formato da resposta

Toda falha responde no mesmo formato. Ramifique pelo code, que é estável, e não pela message, que pode mudar.

{
  "error": {
    "type": "invalid_request",
    "code": "missing_required_param",
    "message": "A required parameter is missing.",
    "param": "cpf",
    "doc_url": "https://docs.id.zapsign.com.br/missing_required_param",
    "request_id": "req_3PK3TA2H0MEMTDSAPREHSY4QC4"
  }
}

string

Categoria do erro, para tratar famílias inteiras: invalid_request, authentication_error, not_found, idempotency_error, payment_error, rate_limit_error ou api_error.

string

Código estável. É o que sua integração deve usar.

string

Descrição em inglês, para diagnóstico. Não mostre ao usuário final.

string

O campo que causou o erro. Vem só quando um campo específico é o responsável.

string

Link direto para o código nesta página.

string

Identificador da requisição. Inclua no contato com o suporte.

400: contrato da requisição

O corpo ou um parâmetro não bate com o formato esperado. Nada foi executado nem cobrado.

`invalid_json`

Status: 400
Message: The request body is not valid JSON.
Ação sugerida: Verifique se o corpo é JSON válido e se o Content-Type é application/json.

`missing_required_param`

Status: 400
Message: A required parameter is missing.
Ação sugerida: O campo faltante vem em param. Compare com o corpo esperado do endpoint.

`invalid_param_type`

Status: 400
Message: A parameter has an invalid type.
Ação sugerida: O campo vem em param. Erro comum: enviar número como string, ou max_age_hours entre aspas.

`invalid_param_value`

Status: 400
Message: A parameter has an invalid value.
Ação sugerida: O campo vem em param. Confira os valores aceitos na referência do endpoint.

`invalid_idempotency_key`

Status: 400
Message: The Idempotency-Key header is invalid.
Ação sugerida: Use de 1 a 256 caracteres, só letras, números, - e _. Um UUID serve.

`idempotency_key_reuse`

Status: 400
Message: The Idempotency-Key was already used for a different request.
Ação sugerida: Uma chave pertence a um corpo. Gere uma chave nova para cada operação de negócio, e reutilize a mesma só nas retentativas dela.

401: autenticação

`invalid_api_key`

Status: 401
Message: The API key provided is invalid.
Ação sugerida: Confira o cabeçalho Authorization: Bearer sk_.... A resposta é a mesma para chave ausente, malformada, desconhecida ou revogada, de propósito. Crie uma chave nova no painel se precisar.

`invalid_token`

Status: 401
Message: The access token provided is invalid or has expired.
Ação sugerida: O access token OAuth foi rejeitado. A resposta é a mesma para token malformado, expirado, adulterado, de outro emissor ou cuja autorização foi revogada, de propósito. Obtenha um token novo pelo fluxo de autorização do ZapSign ID (ou pelo refresh token) e repita a requisição.

402: saldo

`insufficient_balance`

Status: 402
Message: Insufficient balance for this validation.
Ação sugerida: Recarregue no painel. Repetir a requisição não resolve.

403: permissão

`user_verification_required`

HTTP 403. O usuário que autorizou o acesso OAuth ainda precisa confirmar o vínculo entre seu CPF e telefone no painel. A confirmação de outra pessoa da mesma conta não libera suas operações. Entre no painel com o mesmo usuário, confirme seus próprios dados e tente novamente. Esse requisito não substitui os escopos nem a participação na conta. Chamadas autenticadas com API key continuam funcionando sem uma confirmação pessoal adicional. Um resultado de coincidência confirma o vínculo consultado, não a posse do telefone.

`user_verification_not_required`

HTTP 409, somente no painel. A autoverificação está desativada. Nenhuma consulta é iniciada. Atualize o perfil para consultar o acesso disponível.

`user_verification_key_reuse`

HTTP 409, somente no painel. A chave de idempotência já identifica outro conteúdo. Recupere o resultado do intento anterior. Uma nova tentativa explícita deve ter uma nova chave.

`user_verification_in_progress`

HTTP 409, somente no painel. Existe uma comprovação própria em andamento com outra chave. Consulte o identificador disponível no perfil antes de tentar novamente.

`user_already_verified`

HTTP 409, somente no painel. Os dados do usuário já foram confirmados. Atualize o perfil e continue a operação; nenhuma nova consulta ou alteração dos dados confirmados é necessária.

`user_verification_rate_limited`

HTTP 429, somente no painel. O usuário atingiu o limite de 10 tentativas reservadas em 24 horas, considerando todas as suas contas. Aguarde o prazo indicado em Retry-After. Repetir a mesma chave não consome uma nova tentativa.

`user_verification_temporarily_unavailable`

HTTP 503, somente no painel. O orçamento global de consultas de autoverificação foi atingido. Aguarde o prazo indicado em Retry-After. Não altere seu CPF ou telefone para tentar contornar esse limite.

`insufficient_permission`

Status: 403
Message: The API key does not have permission to perform this action.
Ação sugerida: Os endpoints de Chaves de API exigem permission igual a full_access. Uma chave validations_access só cria e consulta validações.

`insufficient_scope`

Status: 403
Message: The access token does not include the scope required for this action.
Ação sugerida: O token OAuth não carrega o escopo exigido pela rota: validations:read para consultas e validations:write para criação e verificação. O cabeçalho WWW-Authenticate da resposta indica o escopo necessário. Refaça a autorização pedindo esse escopo. Os endpoints de Chaves de API não aceitam tokens OAuth; use uma chave sk_ com full_access.

404: recurso

`not_found`

Status: 404
Message: No such resource.
Ação sugerida: Confira o id na URL. Um recurso de outra conta também responde 404, para não revelar a existência dele.

409: idempotência em andamento

`idempotency_in_progress`

Status: 409
Message: A request with the same Idempotency-Key is still in progress.
Ação sugerida: A requisição original ainda está sendo processada. Espere e repita com a mesma chave para receber o resultado dela.

413: tamanho

`request_too_large`

Status: 413
Message: The request body is too large.
Ação sugerida: Os corpos desta API são pequenos. Um 413 costuma indicar que você está enviando um payload que não pertence a este endpoint.

422: regra de negócio

O formato está certo, o conteúdo não. Todos respondem type igual a invalid_request, e o code diz o motivo. O campo responsável vem em param, menos quando o problema é a validação inteira e não um campo dela. Quase todos usam a mesma message: The value provided is invalid. Os que têm mensagem própria trazem a linha Message abaixo.

`consent_not_granted`

Status: 422
Param: consent
Ação sugerida: Envie consent: true. A consulta só é feita com consentimento do titular, e false ou ausente é recusado.

`invalid_cpf`

Status: 422
Param: cpf
Ação sugerida: Envie 11 dígitos, sem pontos nem traço. O dígito verificador é conferido.

`invalid_phone`

Status: 422
Param: phone
Ação sugerida: Use E.164, com + e código do país: +5511999998888.

`phone_not_brazilian`

Status: 422
Param: phone
Ação sugerida: O número precisa começar com +55. Só telefones brasileiros são atendidos.

`phone_not_mobile`

Status: 422
Param: phone
Ação sugerida: Envie um celular. Vínculo entre CPF e telefone não funciona com número fixo.

`phone_length_invalid`

Status: 422
Param: phone
Ação sugerida: Um número brasileiro tem 12 ou 13 dígitos com o código do país, isto é, DDD mais 8 ou 9 dígitos.

`phone_not_reachable`

Status: 422
Param: phone
Message: The phone number cannot receive a verification challenge.
Ação sugerida: O número é um celular brasileiro válido, mas não consegue receber o código. Confirme com o titular qual número ele usa no WhatsApp e tente de novo com esse. Nada foi cobrado e nenhuma validação foi criada, então não há o que consultar depois.

`invalid_max_age_hours`

Status: 422
Param: max_age_hours
Ação sugerida: Envie um inteiro entre 1 e 2400 horas, ou omita o campo para usar a janela padrão.

`invalid_redirect_url`

Status: 422
Param: redirect_url
Ação sugerida: Use uma URL https de host público. Endereços internos, localhost e IPs privados são recusados.

`invalid_external_id`

Status: 422
Param: external_id
Ação sugerida: De 1 a 256 caracteres, só letras, números, - e _. Sem barras, pontos, dois-pontos nem espaços.

`validation_not_verifiable`

Status: 422
Message: This validation is not answered with a code.
Ação sugerida: A validação existe e é sua, mas é de um tipo que não se confirma por código. Só phone_ownership responde a POST /v1/validations/{id}/verify. Confira o type no recurso antes de chamar.

429: limites

Detalhes e estratégia de retentativa em Limites de uso.

`rate_limit_exceeded`

Status: 429
Message: Too many requests. Please retry after the indicated delay.
Ação sugerida: Você passou da taxa da sua conta. Espere o que diz Retry-After e reduza o ritmo.

`concurrency_limit_exceeded`

Status: 429
Message: Too many concurrent requests. Please retry after the indicated delay.
Ação sugerida: Requisições demais em voo ao mesmo tempo. Limite a concorrência do seu lado com uma fila ou um pool.

`auth_failure_limit_exceeded`

Status: 429
Message: Too many failed authentication attempts from this IP. Please retry after the indicated delay.
Ação sugerida: Falhas de autenticação seguidas vindas do seu IP. Corrija a chave antes de repetir: continuar tentando estende o bloqueio.

500: erro nosso

`api_error`

Status: 500
Message: An internal error occurred.
Ação sugerida: Repita com espera exponencial. Se persistir, fale com o suporte com o request_id da resposta.

​400: contrato da requisição

​invalid_json

​missing_required_param

​invalid_param_type

​invalid_param_value

​invalid_idempotency_key

​idempotency_key_reuse

​401: autenticação

​invalid_api_key

​invalid_token

​402: saldo

​insufficient_balance

​403: permissão

​user_verification_required

​user_verification_not_required

​user_verification_key_reuse

​user_verification_in_progress

​user_already_verified

​user_verification_rate_limited

​user_verification_temporarily_unavailable

​insufficient_permission

​insufficient_scope

​404: recurso

​not_found

​409: idempotência em andamento

​idempotency_in_progress

​413: tamanho

​request_too_large

​422: regra de negócio

​consent_not_granted

​invalid_cpf

​invalid_phone

​phone_not_brazilian

​phone_not_mobile

​phone_length_invalid

​phone_not_reachable

​invalid_max_age_hours

​invalid_redirect_url

​invalid_external_id

​validation_not_verifiable

​429: limites

​rate_limit_exceeded

​concurrency_limit_exceeded

​auth_failure_limit_exceeded

​500: erro nosso

​api_error

400: contrato da requisição

`invalid_json`

`missing_required_param`

`invalid_param_type`

`invalid_param_value`

`invalid_idempotency_key`

`idempotency_key_reuse`

401: autenticação

`invalid_api_key`

`invalid_token`

402: saldo

`insufficient_balance`

403: permissão

`user_verification_required`

`user_verification_not_required`

`user_verification_key_reuse`

`user_verification_in_progress`

`user_already_verified`

`user_verification_rate_limited`

`user_verification_temporarily_unavailable`

`insufficient_permission`

`insufficient_scope`

404: recurso

`not_found`

409: idempotência em andamento

`idempotency_in_progress`

413: tamanho

`request_too_large`

422: regra de negócio

`consent_not_granted`

`invalid_cpf`

`invalid_phone`

`phone_not_brazilian`

`phone_not_mobile`

`phone_length_invalid`

`phone_not_reachable`

`invalid_max_age_hours`

`invalid_redirect_url`

`invalid_external_id`

`validation_not_verifiable`

429: limites

`rate_limit_exceeded`

`concurrency_limit_exceeded`

`auth_failure_limit_exceeded`

500: erro nosso

`api_error`