Erros

{
  "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"
  }
}

​

400: contrato da requisição

​

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.

​

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

​

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.

​

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

​

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.

​

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.

​

429: limites

​

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.