Skip to main content

​
Formato de erro

Todas as respostas de erro seguem o mesmo formato: 
{
  "statusCode": 400,
  "message": "Descricao do erro",
  "error": "Bad Request"
}
Para erros de validacao, o campo message pode ser um array: 
{
  "statusCode": 400,
  "message": [
    "amount must not be less than 100",
    "customer.email must be an email"
  ],
  "error": "Bad Request"
}

​
Codigos HTTP

StatusSignificadoAcao recomendada
200Sucesso-
201Criado com sucesso-
400Dados invalidosCorrija os campos indicados no message
401Nao autenticadoVerifique sua API Key ou renove o token JWT
403Sem permissaoVerifique se a key tem acesso ao recurso
404Nao encontradoVerifique o ID enviado
409Conflito de idempotenciaA Idempotency-Key ja foi usada com body diferente
422Entidade nao processavelDados validos mas regra de negocio impede a acao
429Rate limit excedidoAguarde o tempo indicado no header Retry-After
500Erro internoTente novamente. Se persistir, contate o suporte

​
Erros comuns

Os endpoints POST /transactions e POST /withdrawals exigem o header Idempotency-Key com um UUID v4 unico.
O valor minimo de uma transacao e R$ 1,00 (100 centavos). Lembre que todos os valores sao em centavos.
O saldo disponivel na wallet e insuficiente para o saque solicitado. Consulte GET /seller-wallet/gestao.
Sua conta precisa estar com status ACTIVE. Verifique se a documentacao foi aprovada no dashboard.
O ID informado nao existe ou pertence a outro seller. Cada seller so acessa suas proprias transacoes.

​
Tratamento recomendado

async function callThalpay(endpoint, data) {
  const response = await fetch(`https://api.thalbank.com${endpoint}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "x-api-key": process.env.THALPAY_API_KEY,
      "Idempotency-Key": crypto.randomUUID(),
    },
    body: JSON.stringify(data),
  });

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

    switch (response.status) {
      case 401:
        // Renovar token ou verificar API Key
        break;
      case 429:
        // Aguardar Retry-After e tentar novamente
        const retryAfter = response.headers.get("Retry-After");
        await sleep(Number(retryAfter) * 1000);
        return callThalpay(endpoint, data);
      case 400:
      case 422:
        // Erro de validacao — nao adianta retry
        throw new ValidationError(error.message);
      default:
        // Erro inesperado — retry com backoff
        throw new ApiError(error);
    }
  }

  return response.json();
}