Pular para conteúdo

Referência de Erros HTTP

Esta página documenta todos os códigos de erro HTTP que você pode encontrar ao interagir com a API da Videochamada.com.br.

Estrutura de Resposta de Erro

Todas as respostas de erro seguem o seguinte formato JSON:

{
  "message": "Descrição legível do erro",
  "error": "Nome do tipo de erro",
  "statusCode": 400
}

Códigos de Erro por Categoria

400 - Bad Request

Erros de validação de dados ou parâmetros inválidos.

Mensagem Cenário Solução
Invalid parameters Parâmetros da requisição estão inválidos ou faltando Verifique a documentação do endpoint e corrija os parâmetros
Call already ended Tentativa de encerrar uma chamada já encerrada Verifique o status da chamada antes de tentar encerrá-la
Invalid date format Data fornecida não está no formato ISO 8601 Use o formato ISO 8601: 2025-10-16T10:00:00Z
Pagination limit exceeded Limite de paginação excede o máximo permitido (100) Reduza o valor do parâmetro limit para 100 ou menos
Invalid expiration date Data de expiração está no passado Forneça uma data futura para expiresAt

Exemplo de Resposta:

{
  "message": "Call already ended",
  "error": "Bad Request",
  "statusCode": 400
}

403 - Forbidden

Erros de autorização - você está autenticado, mas não tem permissão para realizar a ação.

Mensagem Cenário Solução
IP not allowed IP do requisitor não está na whitelist da API key Adicione seu IP à lista de IPs permitidos da API key
Maximum spending limit reached for this month Limite de gastos mensal foi atingido Aumente o limite de gastos ou aguarde o próximo ciclo de faturamento
Organization not found Organização não existe ou você não tem acesso Verifique se a organização existe e se você tem permissão
Subscription not found Assinatura não existe ou está inativa Ative uma assinatura para a organização
Resource belongs to another project Recurso pertence a outro projeto Verifique se está usando a API key do projeto correto

Exemplo de Resposta:

{
  "message": "Maximum spending limit reached for this month",
  "error": "Forbidden",
  "statusCode": 403
}

Como Resolver: - IP não permitido: Configure a whitelist de IPs na gestão de API keys - Limite de gastos: Ajuste o limite em Configurações → Assinatura - Organização/Subscription: Entre em contato com o administrador da conta

429 - Too Many Requests

Limite de taxa de requisições foi excedido.

Mensagem Cenário Solução
Rate limit exceeded Muitas requisições em curto período Implemente backoff exponencial e respeite os limites

Exemplo de Resposta:

{
  "message": "Rate limit exceeded. Please try again in 60 seconds",
  "error": "Too Many Requests",
  "statusCode": 429
}

Headers da Resposta: 

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1697461200
Retry-After: 60

Como Resolver: - Implemente cache para reduzir requisições repetidas - Use o header Retry-After para saber quando tentar novamente - Considere usar webhooks em vez de polling constante

503 - Service Unavailable

Serviço temporariamente indisponível.

Mensagem Cenário Solução
Service temporarily unavailable Manutenção programada ou sobrecarga Aguarde e tente novamente

Exemplo de Resposta:

{
  "message": "Service temporarily unavailable. Please try again later",
  "error": "Service Unavailable",
  "statusCode": 503
}

Boas Práticas de Tratamento de Erros

1. Sempre Verifique o Status HTTP

const response = await fetch('https://api.videochamada.com.br/api/calls', {
  headers: { 'Authorization': 'Bearer ' + apiToken }
});

if (!response.ok) {
  const error = await response.json();
  console.error(`Erro ${error.statusCode}: ${error.message}`);
  // Trate o erro apropriadamente
}

2. Implemente Retry com Backoff Exponencial

Para erros 429 e 503, implemente retry automático:

async function fetchWithRetry(url, options, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    const response = await fetch(url, options);

    if (response.ok) {
      return response;
    }

    if (response.status === 429 || response.status === 503) {
      const retryAfter = response.headers.get('Retry-After') || Math.pow(2, i);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      continue;
    }

    throw new Error(`HTTP ${response.status}: ${await response.text()}`);
  }
}

3. Log Erros para Análise

Mantenha logs detalhados de erros para troubleshooting:

import logging

try:
    response = requests.get(url, headers=headers)
    response.raise_for_status()
except requests.exceptions.HTTPError as e:
    logging.error(f"HTTP Error: {e.response.status_code} - {e.response.text}")
    # Trate o erro apropriadamente

4. Use Webhooks em Vez de Polling

Para evitar erros 429, prefira webhooks ao invés de fazer polling constante:

// ❌ Evite: Polling a cada 5 segundos
setInterval(async () => {
  const status = await getCallStatus(callId);
}, 5000);

// ✅ Prefira: Configure webhook para call.ended
// Você receberá notificação automática quando a chamada encerrar

Suporte

Se você continuar enfrentando erros após seguir este guia:

Ao entrar em contato, inclua: - Endpoint que está sendo acessado - Código de status HTTP recebido - Mensagem de erro completa - Timestamp aproximado da requisição