Escreva os estados antes de desenhar o indicador
Este é um fluxo proposto para um aplicativo de trilhas desenvolvido por você, não um registro do comportamento observado da API. A pessoa digita offline maps, pede conversas históricas e espera. O aplicativo precisa distinguir formulário ainda não usado, solicitação não resolvida, registros retornados, resposta vazia bem-sucedida e falha. Um único painel em branco não comunica todas essas situações.
Comece com uma tela neutra explicando o que será pesquisado. Digitar não precisa enviar uma solicitação. Após o envio explícito, associe a pergunta à solicitação e mostre um rótulo de carregamento. Preserve a legibilidade e impeça toques repetidos de enviar várias vezes a mesma ação. A animação comunica espera, não avanço comprovado pelo arquivo.
Mantenha a resposta atrasada ligada à pergunta
Imagine que a pessoa mude a entrada para regiões baixadas enquanto a solicitação de offline maps ainda está pendente. É uma interação ilustrativa, não uma busca recuperada. O aplicativo deve decidir se espera, inicia outra solicitação ou permite cancelar a visualização. Qualquer que seja a escolha, a resposta anterior não pode virar silenciosamente a resposta à nova expressão.
Associe cada solicitação à entrada enviada no estado do próprio aplicativo. Quando chegar, confira se a resposta ainda pertence à visualização atual. Descartá-la da tela não equivale a cancelar o trabalho do servidor: uma solicitação já enviada pode concluir com sucesso e ser cobrada. Teste essa diferença em sua implementação.
Trate o vazio bem-sucedido como resultado
Com registros, mostre os campos disponíveis e preserve a identificação de fonte histórica. Com data vazio, use uma mensagem separada explicando que aquela solicitação não retornou registros. Ofereça editar a expressão ou os filtros, preservando-os para uma escolha informada. Não substitua o vazio por publicações populares inventadas.
Recuperações vazias bem-sucedidas custam um crédito, assim como respostas com registros. Isso justifica mudanças de consulta deliberadas, não esconder o vazio como erro. Evite afirmar que não existe conversa relevante em lugar algum; o arquivo é incompleto e a resposta pertence a uma consulta e janela específicas.
Dê ao operador o problema técnico
Uma resposta 400 exige verificar a entrada. Se o aplicativo enviou data inválida ou parâmetro não aceito, não culpe o leitor por um erro de contrato do backend. Um 401 indica chave do serviço ausente ou inválida; recarregar o aplicativo ou pedir login ao leitor não necessariamente corrige a credencial.
Um 402 indica créditos insuficientes da conta do serviço. Encaminhe a decisão ao operador, sem exibir uma fatura ao caminhante. Um 429 exige respeitar Retry-After e reduzir repetições. Como a conta pode ser compartilhada entre leitores, não diga automaticamente a uma pessoa que ela causou o limite.
Separe falha conhecida de resultado desconhecido
O gateway retorna 502 quando a recuperação na fonte falha. O crédito reservado é liberado ou informado como pendente de conciliação. Preserve consulta e páginas anteriores e ofereça uma nova tentativa limitada. Repetições automáticas podem gerar mais solicitações sem ajudar a entender o ocorrido.
Se o aplicativo não recebe resposta, pode não saber se o servidor falhou ou concluiu. Registre a incerteza para conciliação; não mostre uma afirmação definitiva de sucesso ou devolução. A rota pública /v1/status é uma verificação estática de escopo e resposta HTTP, não resolve essa dúvida nem certifica a saúde da busca.
Revise as transições, não só as capturas
Percorra a sequência proposta com quem administra o aplicativo: enviar, editar durante a espera, receber vazio, repetir após falha, carregar outra página e sair. Para cada transição, identifique entrada preservada, conteúdo visível e próxima ação. Uma tela simulada atraente não prova que as transições funcionam.
Mantenha diagnósticos do operador, respostas originais e credenciais fora das mensagens públicas. Dê contexto suficiente para a pessoa continuar preparando a viagem sem depender de uma busca indisponível. Volte a /pt/#field-notes para decisões de orçamento e Mostrar mais que orientam esse fluxo.
