Clickfin

Referência da API
Portal oficial

Erros

Interprete validação, autenticação e falhas de negócio

As respostas de erro combinam código HTTP com categorias específicas do domínio. Essa estrutura ajuda a identificar rapidamente se a falha veio de validação, autenticação, autorização, regra de negócio ou erro interno.

Corpo padrão

Erros de autenticação, autorização e regra de negócio têm status, category e message, e às vezes details:

{
"status": "error",
"category": "API_KEY.SCOPE_REQUIRED",
"message": "This API key does not have the clients:write scope.",
"details": {
"requiredScope": "clients:write"
}
}

Erros de validação

Quando a requisição falha nas regras de formato ou obrigatoriedade, a API costuma responder com 400 e error: VALIDATION_FAILED, acompanhado de detalhes por campo.

Suporte

Toda resposta traz o cabeçalho X-Correlation-Id. Registre-o nos seus logs e envie-o ao suporte da ClickFin junto com o horário da chamada: ele localiza a requisição sem que você precise mandar a chave.

Erros da chave de API

Podem aparecer em qualquer operação chamada com chave, antes da regra de negócio.

HTTPCategoriaQuandoO que fazer
401API_KEY.INVALIDChave inexistente, malformada, revogada, expirada ou de empresa excluída. A resposta é a mesma em todos os casos, de propósito.Não repita. Confira a chave configurada ou gere outra no app.
403API_KEY.SCOPE_REQUIREDA chave não tem o escopo da operação; details.requiredScope diz qual.Acrescente o escopo à chave no app (edição) e repita.
403API_KEY.ROUTE_NOT_ALLOWEDA rota não faz parte da API pública e não aceita chave.Use só as operações desta referência.
403API_KEY.IP_NOT_ALLOWEDO IP de origem não está na lista de IPs permitidos da chave.Chame a partir de um IP da lista ou atualize a lista no app.
403API_KEY.PLAN_NOT_ALLOWEDO plano da licença não inclui acesso à API.Fale com o comercial da ClickFin para mudar de plano.
403BILLING.COMMERCIAL.ACCESS_BLOCKEDA licença está bloqueada comercialmente.Regularize a assinatura no app.
429RATE_LIMIT.EXCEEDEDLimite de requisições excedido (por chave ou por IP).Espere Retry-After segundos e repita com backoff.
503AUTH.SESSION_UNAVAILABLEA credencial não pôde ser verificada por falha temporária do servidor. Não invalida a chave.Repita com backoff exponencial.

Como ler o campo category

  • API_KEY.* e RATE_LIMIT.* vêm da autenticação por chave e do limite de requisições.
  • Categorias de domínio apontam conflitos de regra de negócio, cadastro ou contexto operacional.
  • UNEXPECTED_ERROR representa falha interna inesperada e deve ser tratada como incidente de servidor.

Tratamento recomendado

  • Use o código HTTP para a decisão imediata: 4xx não melhora repetindo; 429 e 503 podem ser repetidos com espera.
  • Use category para mensagens mais precisas, logs e automações de suporte; o texto de message pode mudar.
  • Registre também details quando houver erro de validação por campo.