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.
| HTTP | Categoria | Quando | O que fazer |
|---|---|---|---|
| 401 | API_KEY.INVALID | Chave 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. |
| 403 | API_KEY.SCOPE_REQUIRED | A chave não tem o escopo da operação; details.requiredScope diz qual. | Acrescente o escopo à chave no app (edição) e repita. |
| 403 | API_KEY.ROUTE_NOT_ALLOWED | A rota não faz parte da API pública e não aceita chave. | Use só as operações desta referência. |
| 403 | API_KEY.IP_NOT_ALLOWED | O 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. |
| 403 | API_KEY.PLAN_NOT_ALLOWED | O plano da licença não inclui acesso à API. | Fale com o comercial da ClickFin para mudar de plano. |
| 403 | BILLING.COMMERCIAL.ACCESS_BLOCKED | A licença está bloqueada comercialmente. | Regularize a assinatura no app. |
| 429 | RATE_LIMIT.EXCEEDED | Limite de requisições excedido (por chave ou por IP). | Espere Retry-After segundos e repita com backoff. |
| 503 | AUTH.SESSION_UNAVAILABLE | A 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.*eRATE_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_ERRORrepresenta falha interna inesperada e deve ser tratada como incidente de servidor.
Tratamento recomendado
- Use o código HTTP para a decisão imediata:
4xxnão melhora repetindo;429e503podem ser repetidos com espera. - Use
categorypara mensagens mais precisas, logs e automações de suporte; o texto demessagepode mudar. - Registre também
detailsquando houver erro de validação por campo.