Referência de Códigos de Erro e Status

Guia completo sobre códigos de erro da Smart Money API, códigos de status HTTP e etapas de solução de problemas. Entenda as respostas de erro e resolva problemas de integração rapidamente.

Códigos de Sucesso 2xx

Respostas de sucesso indicam que a solicitação foi processada com sucesso.

Código	Status	Significado
200	OK	Solicitação bem-sucedida. O corpo da resposta contém os dados solicitados.
201	Criado	Recurso criado com sucesso. A resposta inclui o novo recurso.
204	Sem Conteúdo	Solicitação bem-sucedida, mas não há conteúdo para retornar (por exemplo, DELETE).

Exemplo de Resposta 200

JSON

{
  "success": true,
  "data": {
    "total": 42,
    "positions": [...],
    "pagination": {
      "page": 1,
      "limit": 50
    }
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Códigos de Erro do Cliente 4xx

Erros do cliente indicam que a solicitação estava malformada ou inválida. Corrija sua solicitação e tente novamente.

Código	Status	Causa
400	Requisição Inválida	Sintaxe da solicitação malformada. Verifique os parâmetros da consulta, cabeçalhos e corpo da solicitação.
401	Não Autorizado	Credenciais de autenticação ausentes ou inválidas. Verifique sua chave de API ou token JWT.
402	Pagamento Necessário	O pagamento da sua assinatura falhou. Atualize as informações de cobrança na sua conta.
403	Proibido	Autenticado, mas não autorizado para este recurso. Seu plano não inclui este recurso.
404	Não Encontrado	O recurso não existe. Verifique a URL do endpoint e os parâmetros.
429	Muitas Solicitações	Limite de taxa excedido. Aguarde antes de tentar novamente. Verifique o cabeçalho Retry-After.
422	Entidade Não Processável	Validação falhou. Os parâmetros da solicitação são inválidos ou faltam campos obrigatórios.

Exemplos de Erros de Autenticação

Chave de API Ausente (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_MISSING_KEY",
    "message": "Credenciais de autenticação não fornecidas.",
    "resolution": "Inclua sua chave de API no cabeçalho Authorization: Authorization: Bearer sk_live_..."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Chave de API Inválida (401)

JSON

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_KEY",
    "message": "Chave de API inválida ou expirada.",
    "resolution": "Gere uma nova chave de API no seu console em https://smartmoneyapi.com/console"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Limitação de Taxa (429)

Quando você excede sua cota de API, o servidor retorna 429 Muitas Solicitações. Verifique os cabeçalhos da resposta para informações sobre o limite de taxa:

Cabeçalhos HTTP

X-Requests-Remaining: 0
X-Requests-Limit: 200
X-Requests-Reset: 1711116922
Retry-After: 3600

Resposta de Erro de Limite de Taxa

JSON

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Limite diário de solicitações da API (10) excedido.",
    "resolution": "Atualize para o plano Trader ($29/mês, 400 solicitações/dia) ou Pro ($79/mês, 4.000 solicitações/dia).",
    "reset_at": "2026-03-22T09:00:00Z"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Erros de Validação (422)

Erros de validação ocorrem quando os parâmetros da sua solicitação são inválidos ou faltam campos obrigatórios.

JSON

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Falha na validação da solicitação.",
    "details": [
      {
        "field": "symbol",
        "error": "Par de negociação inválido. Formato esperado: BTCUSDT"
      },
      {
        "field": "min_position_size",
        "error": "Deve ser um número positivo"
      }
    ],
    "resolution": "Corrija os erros de validação e tente novamente."
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Códigos de Erro do Servidor 5xx

Erros do servidor indicam um problema do nosso lado. Eles são temporários e geralmente se resolvem rapidamente. Implemente lógica de repetição com backoff exponencial.

Código	Status	Ação
500	Erro Interno	Erro inesperado no servidor. Tente novamente com backoff exponencial.
502	Gateway Inválido	Interrupção temporária do serviço. Tente novamente após alguns segundos.
503	Serviço Indisponível	Manutenção ou interrupção temporária. Verifique a página de status. Tente novamente após o intervalo Retry-After.
504	Tempo Limite do Gateway	A solicitação demorou muito. O servidor pode tê-la processado mesmo assim. Verifique a idempotência.

Exemplo de Erro do Servidor (503)

JSON

{
  "success": false,
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Serviço temporariamente indisponível devido a manutenção.",
    "resolution": "Tente novamente após 5 minutos. Acompanhe o status em https://status.smartmoneyapi.com"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Guia de Solução de Problemas

401 Não Autorizado - Chave de API Inválida

Problema: Recebendo erros 401 mesmo com uma chave de API.

Soluções:

Verifique se a chave de API está incluída no cabeçalho Authorization com o prefixo "Bearer"
Verifique se sua chave de API não expirou ou foi revogada
Certifique-se de que está usando a chave correta (produção, staging ou desenvolvimento)
Gere uma nova chave de API no seu console se a atual foi perdida

403 Proibido - Recurso Não Disponível

Problema: Recebendo erros 403 em determinados endpoints.

Soluções:

Verifique seu nível de API. Alguns endpoints exigem planos Trader ou Pro
Atualize seu plano em /pricing.html para acessar recursos premium
Verifique se a chave de API tem os escopos necessários habilitados
Entre em contato com o suporte se acredita que deveria ter acesso

429 Muitas Solicitações - Limite de Taxa

Problema: Recebendo erros 429 e sendo limitado por taxa.

Soluções:

Implemente lógica de repetição com backoff exponencial (aguarde 1s, 2s, 4s, etc.)
Armazene em cache as respostas para evitar chamadas redundantes à API
Use WebSocket para dados em tempo real em vez de sondar endpoints REST
Atualize seu plano para cotas mais altas (Trader 1,000/dia, Pro 5.000/dia)
Agrupe várias consultas em uma única solicitação sempre que possível

400 Requisição Inválida - Parâmetros Inválidos

Problema: Recebendo erros 400 com solicitações malformadas.

Soluções:

Verifique a documentação da API para parâmetros obrigatórios e opcionais
Verifique os tipos de parâmetros (strings vs números, arrays vs objetos)
Certifique-se de que o JSON é válido e está corretamente formatado
Use URLs de endpoint corretas com parâmetros de caminho apropriados
Verifique erros de digitação nos nomes dos parâmetros da consulta

Erros 5xx do Servidor - Interrupções Temporárias

Problema: Recebendo erros 500, 502, 503 ou 504.

Soluções:

Verifique o status do serviço em https://status.smartmoneyapi.com
Implemente tentativas automáticas com retirada exponencial (máximo 5-10 tentativas)
Aguarde 30-60 segundos antes de tentar novamente erros 503
Use o cabeçalho Retry-After para determinar o tempo de nova tentativa
Assine a página de status para notificações de incidentes

Formato da Resposta de Erro

Todas as respostas de erro seguem um formato consistente:

JSON

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Mensagem de erro legível",
    "details": {...},
    "resolution": "Passos para resolver o problema"
  },
  "timestamp": "2026-03-21T14:35:22Z"
}

Precisa de mais ajuda?

Consulte nossa documentação da API ou entre em contato com o suporte informando o código de erro e os detalhes da solicitação.

Referência da API

Obter Suporte

Tem dúvidas? Consulte nossa documentação ou entre em contato com o suporte.

Abrir Console