Skip to main content
A Linka API usa códigos HTTP padrão e retorna erros em formato JSON estruturado.

Formato de erro

{
  "statusCode": 400,
  "message": "Descrição legivel do erro",
  "error": "Bad Request",
  "details": {
    "field": "amount",
    "reason": "Valor deve ser maior que zero"
  }
}

Códigos HTTP

StatusSignificadoAção recomendada
200Sucesso
201CriadoRecurso criado com sucesso
400Bad RequestVerifique os parametros enviados
401UnauthorizedToken ausente, expirado ou invalido
403ForbiddenSem permissão para este recurso
404Not FoundRecurso não encontrado
409ConflictIdempotency-Key reutilizada com body diferente
422Unprocessable EntityValidação falhou (campos obrigatórios ausentes)
429Too Many RequestsRate limit excedido — aguarde Retry-After
500Internal Server ErrorErro interno — contate o suporte
503Service UnavailableServiço temporariamente indisponível

Erros comuns

Autenticação

ErroCausaSolucao
UNAUTHORIZEDToken ausente ou expiradoEnvie um token valido no header Authorization
INVALID_API_KEYAPI Key revogada ou inexistenteVerifique a key no dashboard
2FA_REQUIREDLogin exige código 2FAInclua twoFactorCode no body

Transações

ErroCausaSolucao
IDEMPOTENCY_KEY_REQUIREDHeader Idempotency-Key ausenteEnvie um UUID v4 no header
IDEMPOTENCY_CONFLICTMesma key com body diferenteUse uma nova key para operação diferente
INVALID_PAYMENT_METHODMétodo de pagamento invalidoUse PIX, BOLETO ou CARD
AMOUNT_TOO_LOWValor abaixo do mínimoEnvie valor >= 100 (R$ 1,00)
SELLER_INACTIVESeller bloqueado ou inativoVerifique o status do seller no dashboard
ACQUIRER_UNAVAILABLEProvedor de pagamento foraTente novamente em alguns minutos

Saques

ErroCausaSolucao
INSUFFICIENT_BALANCESaldo insuficienteVerifique saldo disponível via GET /balance-statement
WITHDRAWAL_LIMIT_EXCEEDEDLimite diário excedidoAguarde o próximo dia útil
INVALID_PIX_KEYChave PIX invalidaVerifique o formato da chave

Tratamento de erros

async function createTransaction(payload) {
  const response = await fetch('https://api.linka.com/transactions', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer sk_live_...',
      'Idempotency-Key': crypto.randomUUID(),
      'Content-Type': 'application/json',
    },
    body: JSON.stringify(payload),
  });

  if (!response.ok) {
    const error = await response.json();

    switch (response.status) {
      case 401:
        // Renovar token e tentar novamente
        break;
      case 429:
        // Aguardar e tentar novamente
        const retryAfter = response.headers.get('Retry-After');
        await new Promise(r => setTimeout(r, retryAfter * 1000));
        return createTransaction(payload);
      case 400:
      case 422:
        // Erro de validação — corrigir os dados
        console.error('Validação:', error.message, error.details);
        break;
      default:
        // Erro inesperado
        console.error('Erro:', error);
    }

    throw new Error(error.message);
  }

  return response.json();
}