Handling iGps API Errors: 400, 401, 429, and 500 Codes

A iGps usa códigos de status HTTP padrão para indicar sucesso ou falha. Entender esses códigos permite construir integrações resilientes que tratam erros de forma elegante.

Códigos de Status HTTP

Código	Nome	Quando Ocorre
`200`	OK	Requisição bem-sucedida. Verifique os campos `status` por veículo na resposta.
`400`	Bad Request	O corpo da requisição é inválido (por exemplo, campos obrigatórios ausentes, formato de chassi inválido).
`401`	Unauthorized	O token de acesso está ausente, é inválido ou expirou.
`429`	Too Many Requests	Limite de requisições excedido. Reduza a frequência das requisições e tente novamente.
`500`	Internal Server Error	Erro no lado do servidor. Tente novamente com backoff exponencial.

Tratando 401 Unauthorized

Uma resposta 401 significa que o token Bearer fornecido está ausente, malformado ou expirou. Os tokens emitidos por POST /api/v1/auth/token são válidos por 1 hora. Quando um 401 ocorre, sua aplicação deve obter um novo token e reenviar a requisição original.

import requests

def get_token(client_id, client_secret):
    resp = requests.post(
        "https://api.igps.com.br/api/v1/auth/token",
        json={"client_id": client_id, "client_secret": client_secret}
    )
    resp.raise_for_status()
    return resp.json()["access_token"]

token = get_token(client_id, client_secret)

response = requests.post(
    "https://api.igps.com.br/api/v1/veiculos/posicoes",
    headers={"Authorization": f"Bearer {token}"},
    json={"chassis": chassis_list}
)
if response.status_code == 401:
    token = get_token(client_id, client_secret)  # Renovar token expirado
    response = requests.post(
        "https://api.igps.com.br/api/v1/veiculos/posicoes",
        headers={"Authorization": f"Bearer {token}"},
        json={"chassis": chassis_list}
    )

Para evitar erros 401 de forma proativa, acompanhe o horário de emissão do token e renove-o antes que expire, em vez de esperar que a API o rejeite.

Tratando 429 Too Many Requests

Uma resposta 429 significa que sua aplicação excedeu o limite de requisições da API. A estratégia recomendada é o backoff exponencial: aguardar progressivamente mais tempo entre tentativas para reduzir a pressão sobre a API e aumentar a probabilidade de uma resposta bem-sucedida.

import time

def query_with_retry(chassis_list, token, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(
            "https://api.igps.com.br/api/v1/veiculos/posicoes",
            headers={"Authorization": f"Bearer {token}"},
            json={"chassis": chassis_list}
        )
        if response.status_code == 429:
            time.sleep(2 ** attempt)
            continue
        return response
    raise Exception("Numero maximo de tentativas excedido")

No exemplo acima, os tempos de espera entre as tentativas são de 1 s, 2 s e 4 s, respectivamente. Ajuste max_retries e a base do backoff para atender aos requisitos de latência da sua aplicação.

Erros no Nível do Veículo

É importante distinguir entre erros no nível HTTP e erros no nível do veículo:

Erros HTTP (4xx / 5xx) indicam que a requisição inteira falhou. Nenhum dado de posição é retornado.
nao_encontrado no nível do veículo é retornado dentro de uma resposta 200 OK. A requisição em si foi bem-sucedida, mas um ou mais veículos individuais não puderam ser encontrados.

Portanto, uma resposta 200 ainda pode conter veículos que não foram encontrados. Sempre itere sobre o array resultados e verifique o campo status para cada veículo antes de tentar ler seus campos latitude, longitude ou timestamp. Para mais detalhes sobre o status nao_encontrado, consulte Posições de Veículos.

Não tente novamente em erros 400. Estes indicam um problema no corpo da sua requisição que deve ser corrigido antes de tentar novamente.

Introdução

Conceitos Principais

Guias

Handling iGps API Errors: 400, 401, 429, and 500 Codes

Códigos de Status HTTP

Tratando 401 Unauthorized

Tratando 429 Too Many Requests

Erros no Nível do Veículo