Erros e códigos

Toda resposta de erro segue o mesmo schema, independente do endpoint. Trate erros pelo error.code (string estável), nunca pelo error.message (texto pode mudar).

Schema padrão

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limite de 100 requisições/minuto excedido. Tente novamente em 23s.",
    "details": {
      "limit": 100,
      "window_seconds": 60,
      "retry_after_seconds": 23
    },
    "request_id": "req_01HVZX9YQB7M3J2K5N8P1R4T6W"
  }
}

Campo	Descrição
code	String estável UPPER_SNAKE_CASE. Use para lógica de tratamento
message	Texto pt-BR (ou en-US se Accept-Language: en-US) para humanos
details	Objeto contextual (campo inválido, retry-after, etc). Varia por código
request_id	ID de correlação. Sempre informe ao suporte

Mapeamento HTTP × códigos de aplicação

4xx: erro do cliente

HTTP	Code	Causa	Ação recomendada
400	VALIDATION_FAILED	Campo ausente ou tipo errado	Corrija payload, não retente
400	MALFORMED_JSON	JSON inválido	Corrija sintaxe
400	INVALID_ADDRESS	Endereço crypto não-canônico	Normalize antes (lowercase ETH, base58 BTC)
400	UNSUPPORTED_BLOCKCHAIN	Blockchain não suportada	Use enum: BITCOIN, ETHEREUM, TRON, SOLANA, POLYGON, BSC
401	UNAUTHENTICATED	Sem header ou token inválido	Reautentique
401	TOKEN_EXPIRED	JWT expirou	Use /auth/refresh
401	MFA_STEP_UP_REQUIRED	Operação sensível exige MFA recente	Faça /auth/mfa/verify antes
403	FORBIDDEN_SCOPE	API key sem escopo necessário	Gere nova key com escopo correto
403	MODULE_NOT_ENTITLED	Tenant não tem o módulo no plano	Upgrade ou ative módulo no admin
404	RESOURCE_NOT_FOUND	Recurso inexistente ou em outro tenant	Não retente
409	IDEMPOTENCY_CONFLICT	Mesma Idempotency-Key com body diferente	Use chave nova
409	DUPLICATE_RESOURCE	Recurso único já existe (ex: external_id)	Trate como sucesso silencioso
409	STATE_CONFLICT	Operação inválida no estado atual (ex: resolver alerta já resolvido)	Releia o estado
422	BUSINESS_RULE_FAILED	Regra de negócio bloqueou (ex: KYC pendente)	Veja details.rule_id
429	RATE_LIMITED	Limite por tenant/IP/endpoint atingido	Respeite Retry-After

5xx: erro do servidor

HTTP	Code	Causa	Ação recomendada
500	INTERNAL_ERROR	Bug inesperado	Retry com backoff exponencial. Se persistir, abra ticket com request_id
502	UPSTREAM_UNAVAILABLE	Bureau externo (Exato, Chainalysis) fora	Retry após 30s; nosso fallback geralmente cobre em <60s
503	SERVICE_DEGRADED	Modo degradado (alguma integração caiu)	Decisão pode vir REVIEW em vez de APPROVE; reprocesse depois
504	UPSTREAM_TIMEOUT	Bureau passou de 2s	Idem 502

Estratégia de retry

Cuidado

Nunca retry em 4xx (exceto 408, 429). 4xx é erro do cliente e não vai resolver sozinho.

const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);

async function callWithRetry(fn, maxAttempts = 4) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (!RETRYABLE.has(err.status) || attempt === maxAttempts) throw err;
      const retryAfter = err.headers?.['retry-after'];
      const delayMs = retryAfter
        ? parseInt(retryAfter) * 1000
        : Math.min(1000 * Math.pow(2, attempt), 30000);
      await new Promise(r => setTimeout(r, delayMs + Math.random() * 500));
    }
  }
}

Códigos especiais para fluxos de compliance

Code	Quando aparece	Significado
KYC_TIER_INSUFFICIENT	Transação acima do limite para o tier do cliente	Faça upgrade KYC (ENHANCED) antes
SANCTIONS_HIT	Cliente ou contraparte em lista OFAC/ONU/COAF	Não desbloquear sem revisão compliance
TRAVEL_RULE_REQUIRED	Transação ≥ R$ 1.000 entre VASPs	Envie IVMS101 antes de liquidar
COAF_REPORTING_TRIGGERED	Transação dispara SAR automático	Aguarde envio em até 24h

Como reportar um erro

Quando abrir ticket no suporte (dev-support@sentinexrisk.com), envie:

1. request_id da resposta de erro
2. Timestamp da chamada (UTC)
3. Endpoint + método HTTP
4. tenant_id (não envie payload com PII!)

Tempo de resposta SLA: P1 < 1h, P2 < 4h úteis, P3 < 1 dia útil.