Pular para o conteúdo principal

Formato de Resposta de Erro

Todos os erros seguem um formato consistente:

Códigos de Status HTTP

  • 200 OK: Requisição bem-sucedida;
  • 400 Bad Request: Parâmetros de requisição inválidos;
  • 401 Unauthorized: Chave de API ausente ou inválida;
  • 403 Forbidden: Chave de API não tem permissões necessárias ou IP não permitido;
  • 406 Not Acceptable: Requisição não pode ser processada (ex: mercado fechado);
  • 429 Too Many Requests: Limite de taxa excedido;
  • 500 Internal Server Error: Erro do servidor.

Códigos de Erro

Erros de Colocação de Ordem

PO1
Descrição: Preço é inválido (deve estar entre 0-100 ticks para ordens limitadas, ou value_cents deve ser positivo para ordens a mercado)
PO2
Descrição: Quantidade é inválida (deve ser positiva)
PO3
Descrição: Conta não tem saldo suficiente para fazer a ordem
PO4
Descrição: Conta não tem contratos suficientes para vender
PO5
Descrição: Mercado não tem liquidez suficiente para executar a ordem
PO6
Descrição: Ordem não encontrada (ao tentar cancelar)
PO7
Descrição: Usuário não está autorizado a realizar esta ação
PO8
Descrição: Mercado está fechado e não está mais aceitando ordens
-1
Descrição: Ocorreu um erro inesperado

Erros de Autenticação

401 Unauthorized

Causas:
  • Cabeçalho X-Api-Key ausente
  • Chave de API inválida
  • Chave de API expirou
  • Chave de API está desabilitada
Solução: Verifique se sua chave de API está correta e ativa em Perfil → Segurança

403 Forbidden

Causas:
  • Seu endereço IP não está na whitelist da chave de API
Solução: Adicione seu endereço IP à lista de IPs permitidos da chave de API

Limitação de Taxa

429 Too Many Requests

Descrição: Você excedeu o limite de taxa para este endpoint Cabeçalhos de Resposta:
  • Retry-After: Número de segundos para esperar antes de tentar novamente
Solução: Aguarde o tempo especificado antes de fazer outra requisição

Boas Práticas de Tratamento de Erros

  1. Verificar Códigos de Status: Sempre verifique códigos de status HTTP antes de processar respostas
  2. Tratar Limites de Taxa: Implemente backoff exponencial para erros de limite de taxa
  3. Validar Entrada: Valide todos os parâmetros antes de enviar requisições
  4. Verificar Status do Mercado: Verifique se o mercado está aberto antes de fazer ordens
  5. Monitorar Saldo: Verifique o saldo disponível antes de fazer ordens
  6. Registrar Erros: Registre códigos e mensagens de erro para depuração

Exemplo de Tratamento de Erros