Erros

Todas as APIs da Liqi utilizam um formato padrão para retornar erros. Esta página documenta o formato de resposta, os códigos HTTP utilizados e orientações para tratamento de erros na sua integração.

Formato da resposta de erro

Quando uma requisição falha, a API retorna um objeto JSON com a seguinte estrutura:

JSON

{
  "statusCode": 400,
  "message": "Validation failed: 'ticker' must be a non-empty string",
  "error": "Bad Request"
}

Campos da resposta

Campo	Tipo	Descrição
`statusCode`	number	Código HTTP do erro (400, 401, 404, etc.)
`message`	string	Mensagem descritiva do erro. Pode conter detalhes de validação
`error`	string	Nome padrão do status HTTP (Bad Request, Not Found, etc.)

Em alguns endpoints, o campo message pode ser um array de strings quando há múltiplos erros de validação:

JSON

{
  "statusCode": 400,
  "message": [
    "'amount' must be a positive number",
    "'currency' must be one of: BRL, USDC"
  ],
  "error": "Bad Request"
}

Códigos HTTP

Sucesso

Código	Significado	Quando
`200`	OK	Requisição processada com sucesso
`201`	Created	Recurso criado com sucesso
`204`	No Content	Operação executada, sem corpo na resposta

Erros do cliente (4xx)

Código	Significado	Causa comum
`400`	Bad Request	Body inválido, parâmetros ausentes ou formato incorreto
`401`	Unauthorized	Credencial ausente, inválida ou expirada
`403`	Forbidden	Credencial válida mas sem permissão para o recurso
`404`	Not Found	Recurso não existe ou ID inválido
`409`	Conflict	Operação conflitante (duplicata, status incompatível)
`422`	Unprocessable Entity	Dados válidos sintaticamente mas rejeitados pela regra de negócio
`429`	Too Many Requests	Rate limit excedido

Erros do servidor (5xx)

Código	Significado	O que fazer
`500`	Internal Server Error	Erro inesperado no servidor. Tente novamente e, se persistir, contate o suporte
`502`	Bad Gateway	Problema de comunicação entre serviços. Tente novamente em alguns segundos
`503`	Service Unavailable	Serviço temporariamente indisponível. Consulte a página de status
`504`	Gateway Timeout	Timeout na comunicação interna. Tente novamente com backoff

Erros de validação

Para endpoints que recebem body JSON, a API valida todos os campos e retorna mensagens descritivas:

Bash

curl -X POST "https://api.liqi.com.br/v1/auth/login" \
  -H "Content-Type: application/json" \
  -d '{}'

JSON

{
  "statusCode": 400,
  "message": [
    "apiKey should not be empty",
    "apiKey must be a string",
    "secretKey should not be empty",
    "secretKey must be a string"
  ],
  "error": "Bad Request"
}

Tratamento recomendado

Estrutura básica

TypeScript

async function callApi(url: string, options?: RequestInit) {
  const response = await fetch(url, options);

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

    switch (response.status) {
      case 400:
        // Erro de validação — corrigir parâmetros
        console.error("Validação:", error.message);
        break;

      case 401:
        // Token expirado — renovar e tentar novamente
        await refreshToken();
        return callApi(url, options);

      case 404:
        // Recurso não encontrado
        console.error("Recurso não encontrado:", url);
        return null;

      case 429:
        // Rate limit — aguardar e tentar novamente
        const retryAfter = parseInt(
          response.headers.get("Retry-After") || "5",
          10
        );
        await sleep(retryAfter * 1000);
        return callApi(url, options);

      default:
        // Erro inesperado
        console.error(`Erro ${response.status}:`, error.message);
        throw new Error(error.message);
    }
  }

  // Se 204, não tem body
  if (response.status === 204) return null;

  return response.json();
}

function sleep(ms: number) {
  return new Promise((resolve) => setTimeout(resolve, ms));
}

Python

import requests
import time

def call_api(url, **kwargs):
    response = requests.request(**kwargs, url=url)

    if response.status_code == 429:
        retry_after = int(response.headers.get("Retry-After", 5))
        time.sleep(retry_after)
        return call_api(url, **kwargs)

    if response.status_code == 401:
        refresh_token()
        return call_api(url, **kwargs)

    response.raise_for_status()

    if response.status_code == 204:
        return None

    return response.json()

Erros por API

Cada API possui códigos de erro específicos além dos códigos HTTP padrão:

API	Prefixo de código	Documentação
TIDC v1	`1xxx`, `2xxx`	Códigos de erro TIDC v1
CaaS	`CAAS_*`	Códigos de erro CaaS
Public / Developer	Códigos HTTP padrão	Esta página

Para uma referência completa e pesquisável de todos os códigos de erro, consulte o Índice de Erros.

Próximos passos

Índice de Erros — Referência pesquisável de todos os códigos de erro
Rate Limits — Limites de requisição e header Retry-After
Autenticação — Resolver erros 401 e 403