Erros & Status HTTP

---

Tabela de codigos de erro

Codigo	Significado	Causas comuns
400	Bad Request	Campos obrigatorios ausentes, tipos invalidos
401	Unauthorized	Token ausente, invalido ou expirado
403	Forbidden	Role insuficiente para o endpoint
404	Not Found	Recurso nao existe ou nao pertence ao usuario
422	Unprocessable Entity	Transicao de status invalida, saldo insuficiente
502	Bad Gateway	Servico externo falhou (ASAAS ou OpenRouteService)

---

Formato padrao de resposta de erro

Todos os erros seguem o schema:

{
  "detail": "Mensagem descritiva do erro"
}

Para erros de validacao (400), o FastAPI retorna o formato Pydantic:

{
  "detail": [
    {
      "type": "missing",
      "loc": ["body", "origin_address"],
      "msg": "Field required",
      "input": {}
    }
  ]
}

---

Exemplos de erro por codigo

401 — Token expirado

{"detail": "Token expirado ou invalido"}

Solucao: Refaca o login ou use o refresh_token para obter um novo access_token. Ver Autenticacao.

403 — Role insuficiente

{"detail": "Acesso negado: role insuficiente"}

Solucao: Verifique se esta usando credenciais com a role correta para o endpoint.

404 — Entrega nao encontrada

{"detail": "Entrega nao encontrada"}

422 — Transicao de status invalida

{"detail": "Transicao invalida: entrega ja esta em in_progress"}

422 — Saldo insuficiente

{"detail": "Saldo insuficiente para saque"}

502 — Servico externo indisponivel

{"detail": "Erro ao calcular rota: servico OpenRouteService indisponivel"}

---

Tratamento de erros em codigo

Python

import requests
import time

def call_with_retry(url: str, headers: dict, max_retries: int = 3) -> dict:
    """Chamada com backoff exponencial para erros 502."""
    for attempt in range(max_retries):
        resp = requests.get(url, headers=headers)

        if resp.status_code == 200:
            return resp.json()

        if resp.status_code == 401:
            raise Exception("Token invalido ou expirado — refaca o login")

        if resp.status_code == 403:
            raise Exception("Acesso negado — verifique sua role")

        if resp.status_code == 404:
            raise Exception(f"Recurso nao encontrado: {url}")

        if resp.status_code == 422:
            detail = resp.json().get("detail", "Erro de validacao")
            raise Exception(f"Dado invalido: {detail}")

        if resp.status_code == 502:
            wait = 2 ** attempt  # 1s, 2s, 4s
            print(f"Servico externo falhou, aguardando {wait}s (tentativa {attempt + 1}/{max_retries})")
            time.sleep(wait)
            continue

        resp.raise_for_status()

    raise Exception(f"Falhou apos {max_retries} tentativas")

JavaScript

async function callWithRetry(url, headers, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const resp = await fetch(url, { headers });

    if (resp.ok) return resp.json();

    const body = await resp.json().catch(() => ({}));
    const detail = body.detail ?? resp.statusText;

    if (resp.status === 401) throw new Error("Token invalido ou expirado");
    if (resp.status === 403) throw new Error("Acesso negado — verifique sua role");
    if (resp.status === 404) throw new Error(`Recurso nao encontrado: ${url}`);
    if (resp.status === 422) throw new Error(`Dado invalido: ${detail}`);

    if (resp.status === 502) {
      const wait = 2 ** attempt * 1000; // 1s, 2s, 4s
      console.warn(`Servico externo falhou, aguardando ${wait}ms`);
      await new Promise((r) => setTimeout(r, wait));
      continue;
    }

    throw new Error(`HTTP ${resp.status}: ${detail}`);
  }
  throw new Error(`Falhou apos ${maxRetries} tentativas`);
}

---

Estrategia de retry para 502

Para erros 502 (servico externo indisponivel), use backoff exponencial:

Tentativa	Aguardar
1	1 segundo
2	2 segundos
3	4 segundos
4+	Desistir e notificar

Quando nao fazer retry

Erros 400, 401, 403, 404 e 422 sao erros do cliente — nao adianta tentar novamente sem corrigir a requisicao.

Rate limit de localizacao

O endpoint PUT /api/v1/locations/me aceita no maximo 1 requisicao a cada 10 segundos por motorista. Exceder esse limite retorna 429 Too Many Requests.