Rate Limits e Tratamento de Erros

Para garantir a estabilidade da API, aplicam-se Rate Limits a determinados endpoints.

Limites

100 pedidos por hora (POST)

Ilimitado (GET / PUT)

Os Rate Limits aplicam-se por endereço IP

Códigos de estado HTTP

Status	Description
400	Request-Body inválido ou campos obrigatórios em falta
401	API-Key ausente ou inválida
404	Encomenda não encontrada
429	Rate Limit excedido
500	Erro interno do servidor

Respostas de erro

Todos os erros seguem um formato JSON uniforme.

json

// 429 Rate Limit
{ "error": "Rate limited" }

// 400 Validation Error
{
  "error": "Validation failed",
  "details": {
    "customerName": { "_errors": ["Required"] },
    "type": { "_errors": ["Invalid enum value"] }
  }
}

// 404 Not Found
{ "error": "Order not found" }

Boas Práticas

Polling: Consulta GET /api/vendor/orders no máximo a cada 30 segundos.

Retry: Em caso de 429 ou 5xx, aguarda e tenta novamente com backoff exponencial.

Idempotência: POST cria sempre uma nova encomenda. Verifica primeiro se a encomenda já existe.

Retry com Backoff

Em caso de erros de Rate Limit (429), recomendamos backoff exponencial:

javascript

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

    if (res.status === 429 || res.status >= 500) {
      const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
      await new Promise((r) => setTimeout(r, delay));
      continue;
    }

    return res;
  }

  throw new Error("Max retries exceeded");
}