# Nenhum resultado ou erro API: como fazer a distinção?

> Distingue resultado vazio, resposta parcial e erro na API ROOTE. Verifique coordenadas, filtros, cobertura e limites para mostrar a mensagem correta.

Source: https://www.roote.ai/pt/guides/sem-resultados-ou-erro-api-como-diferenciar/
Language: pt
Author: ROOTE

Uma API sem resultados e uma API com erro exigem tratamentos diferentes. Uma busca bem-sucedida pode não retornar nenhum local dentro da área consultada. Uma falha de rede, limite atingido ou fonte indisponível impede, ao contrário, concluir a partir da busca.

Para ROOTE, verifique a resposta HTTP, em seguida o estado de negócio, a coleção esperada e a cobertura. Esse procedimento evita mostrar “nenhum banheiro” quando a chamada aos Serviços falhou ou “nenhuma parada” após um tempo limite ultrapassado.

## Ler os três níveis de uma resposta

| Nível | A verificar | Conclusão possível |
| --- | --- | --- |
| Transporte | Conexão, tempo e estado HTTP | A requisição foi concluída? |
| Contrato | JSON válido, versão e campos esperados | A resposta é utilizável? |
| Resultado de negócio | status, coleções, coverage, avisos e meta | O que sabemos dentro do perímetro solicitado? |

Um código HTTP 200 não é suficiente para validar uma busca. A resposta pode indicar execução parcial ou estado de erro. Por outro lado, um 404 em uma rota não é forma normal de expressar uma coleção vazia: verifique a URL e o contrato.

## Compreender success, empty, partial e error

| Status | Tratamento recomendado |
| --- | --- |
| success | Mostrar as entidades após validação e manter os limites |
| empty | Indicar que nenhum resultado foi retornado para essa busca |
| partial | Mostrar as informações utilizáveis com seus avisos |
| error | Apresentar a busca como indisponível; não concluir que não há locais |

A ausência de resultado refere-se a uma requisição e fontes conhecidas. Ela não prova que nenhum serviço exista fisicamente. Uma cobertura não exaustiva, um filtro restritivo ou um limite aplicado podem reduzir os resultados.

## Uma árvore de decisão para sua interface

```
1. La requête a-t-elle abouti ?
   Non → indisponibilité réseau ou délai dépassé.
2. Le statut HTTP est-il acceptable selon le contrat ?
   Non → traiter le code et le message d'erreur.
3. Le JSON respecte-t-il le schéma attendu ?
   Non → réponse inexploitable, jamais "aucun résultat".
4. Le statut métier est-il error ?
   Oui → recherche indisponible.
5. Le statut est-il partial ou la couverture limitée ?
   Oui → résultats utilisables + avertissement.
6. La collection attendue est-elle vide ?
   Oui → aucun résultat retourné dans ce périmètre.
   Non → afficher les résultats et leurs limites.
```

## Verificar parâmetros na ordem correta

Verifique primeiro latitude e longitude, sua ordem e a cidade obtida. Depois confira a unidade do raio e o vocabulário dos filtros. A API Services usa types=toilets; uma URL de mapa usa modes=toilets. Esses parâmetros pertencem a contratos diferentes.

Amplie depois uma só dimensão por vez: aumente o raio dentro dos limites da rota ou retire um filtro para teste explícito. Guarde o registro da requisição inicial. Se ampliar automaticamente, informe o novo perímetro ao usuário.

[Construir uma busca API em torno de coordenadas GPS](https://www.roote.ai/pt/guides/como-pesquisar-paradas-de-transporte-proximas-com-uma-api/)

## Tratar uma fonte indisponível sem perder as outras

Uma resposta parcial pode conter locais de fontes que responderam enquanto outra falhou. Mantenha esses resultados, suas atribuições e o aviso pertinente. Não apresente a lista como exaustiva e não substitua campos faltantes por valores padrão enganosos.

Uma informação antiga armazenada em cache também pode ser útil se sua política permitir essa alternativa. Deve permanecer identificada como antiga. O horário da recepção da sua requisição não atualiza a observação original.

## Adaptar mensagens e retomadas

| Situação | Mensagem a adaptar em sua interface | Ação |
| --- | --- | --- |
| empty | Nenhum resultado retornado nesta área com esses filtros | Modifique a área ou os filtros |
| partial | Alguns resultados estão disponíveis; a busca está incompleta | Mostrar os resultados e o aviso |
| Erro de validação | A busca contém um parâmetro inválido | Corrigir a requisição |
| Autenticação ou direitos | Este acesso não permite esta busca | Verificar a conta ou o token |
| Limite ou indisponibilidade | A busca está temporariamente indisponível | Seguir as instruções de retomada |

Para um 429, consulte as instruções do serviço e o possível Retry-After. Um erro 400 requer correção dos argumentos; repetir a mesma requisição não resolve. Não transforme um 401 em chamada anônima automática se o usuário forneceu um token.

[Referência de erros da API ROOTE](https://doc.roote.ai/roote-api/errors)

[Estado dos serviços ROOTE](https://status.roote.ai/)

## Testar os quatro estados antes de publicar

Prepare respostas de teste completas, vazias, parciais e com erro, assim como um JSON inválido e um tempo limite excedido. Verifique a mensagem exibida, os resultados mantidos e o número de tentativas. O teste essencial é que uma falha nunca produza uma afirmação de ausência de serviços.

[Aplicar essas regras a um assistente IA](https://www.roote.ai/pt/guides/como-criar-um-assistente-que-encontre-mobilidade-ao-redor-de-um-endereco/)

[Compreender os formatos de dados de mobilidade](https://www.roote.ai/pt/guides/gtfs-gtfs-rt-e-gbfs-quais-diferencas/)

## Perguntas frequentes

### Uma lista vazia prova a ausência de banheiros?

Não. Ela apenas indica que nenhum resultado foi retornado para essa busca e as fontes consultadas.

### Pode-se mostrar uma resposta parcial?

Sim, se as entidades usadas forem válidas e se você mantiver os avisos e limites necessários.

### Deve-se relançar cada erro?

Não. Corrija erros de parâmetros ou acesso; limite as tentativas para incidentes transitórios e respeite as instruções do serviço.