Pular para o conteúdo principal

Formato de Resposta de Erro

A KillB retorna respostas de erro padronizadas:
{
  "errorCode": "USER.0001",
  "message": ["Usuário não encontrado"],
  "statusCode": "404",
  "arguments": [
    {
      "key": "userId",
      "value": "invalid-id"
    }
  ]
}

Códigos de Status HTTP

StatusSignificadoAção
200SucessoProcessar resposta
201CriadoRecurso criado com sucesso
400Requisição InválidaCorrigir parâmetros da requisição
401Não AutorizadoAtualizar token
403ProibidoVerificar permissões
404Não EncontradoRecurso não existe
409ConflitoRecurso já existe
429Muitas RequisiçõesImplementar backoff
500Erro do ServidorTentar novamente com backoff

Códigos de Erro Comuns

Erros de Autenticação

CódigoMensagemSolução
AUTH.0001Credenciais inválidasVerificar email/senha
AUTH.0002Token expiradoAtualizar token de acesso
AUTH.0003Token inválidoRe-autenticar

Erros de Usuário

CódigoMensagemSolução
USER.0001Usuário não encontradoVerificar ID do usuário
USER.0002Documento inválidoVerificar formato do documento
USER.0003Email já existeUsar email diferente
USER.0004Usuário menor de idadeUsuário deve ter 18+

Erros de Ramp

CódigoMensagemSolução
RAMP.0001Cotação expiradaCriar nova cotação
RAMP.0002Saldo insuficienteVerificar saldo pré-financiado
RAMP.0003Limite do usuário excedidoAtualizar nível KYC
RAMP.0004Conta inválidaVerificar status da conta

Estratégia de Tratamento de Erros

class KillBAPIError extends Error {
  constructor(response) {
    super(response.message.join(', '));
    this.errorCode = response.errorCode;
    this.statusCode = response.statusCode;
    this.arguments = response.arguments;
  }
}

const makeAPIRequest = async (endpoint, options) => {
  try {
    const response = await fetch(endpoint, options);
    
    if (!response.ok) {
      const error = await response.json();
      throw new KillBAPIError(error);
    }
    
    return await response.json();
    
  } catch (error) {
    if (error instanceof KillBAPIError) {
      // Lidar com erros da API
      console.error(`Erro da API ${error.errorCode}:`, error.message);
      
      if (error.statusCode === '401') {
        // Token expirado, atualizar
        await refreshToken();
        return makeAPIRequest(endpoint, options);
      }
      
      if (error.errorCode === 'RAMP.0001') {
        // Cotação expirada, obter nova
        const newQuote = await getNewQuotation();
        // Tentar novamente com nova cotação
      }
    }
    
    throw error;
  }
};

Lógica de Retry

Implemente backoff exponencial:
const retryWithBackoff = async (fn, maxRetries = 3) => {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (i === maxRetries - 1) throw error;
      
      // Não tente novamente erros de cliente (4xx)
      if (error.statusCode && error.statusCode < 500) {
        throw error;
      }
      
      // Backoff exponencial
      const delay = Math.pow(2, i) * 1000;
      await new Promise(resolve => setTimeout(resolve, delay));
    }
  }
};

// Uso
const user = await retryWithBackoff(() => createUser(userData));

Mensagens Amigáveis ao Usuário

Mapeie erros técnicos para mensagens de usuário:
const getUserMessage = (error) => {
  const messages = {
    'AUTH.0002': 'Sua sessão expirou. Por favor, faça login novamente.',
    'USER.0003': 'Este email já está registrado.',
    'RAMP.0001': 'A cotação de preço expirou. Por favor, tente novamente.',
    'RAMP.0003': 'O valor da transação excede seu limite. Por favor, verifique sua identidade para aumentar limites.'
  };
  
  return messages[error.errorCode] || 'Ocorreu um erro. Por favor, tente novamente.';
};

Próximos Passos