Uma tela de busca precisa de mais que resultados ou erro

Um roteiro de telas, não um painel de status

Estes são estados propostos para um aplicativo de trilhas criado por você. Não são respostas capturadas, demonstrações em funcionamento nem provas de que existam registros sobre offline maps. A pessoa usa seu aplicativo; o operador da conta API administra a credencial e os créditos. Dê a cada um informações sobre as quais possa agir.

Antes da primeira busca, explique que a função lê conversas históricas. Uma sugestão como offline maps pode ajudar a começar, mas não mostre recomendações inventadas como se uma busca já tivesse acontecido. Mantenha uma ação Buscar explícita para que digitar e explorar o formulário não precisem gerar uma solicitação paga.

Carregamento: mantenha a pergunta visível

Enquanto a solicitação estiver pendente, preserve a consulta enviada e os filtros selecionados. Marque a área de resultados como carregando, impeça envios duplicados dessa ação e ofereça uma descrição acessível em texto junto de qualquer animação. Um atraso isolado não identifica indisponibilidade do serviço nem sua causa.

Se a pessoa mudar a consulta antes de chegar uma resposta anterior, associe cada resposta à entrada que foi enviada. Não coloque resultados da pergunta antiga sob a nova sem avisar. Esse é um comportamento de implementação a testar no aplicativo, não uma garantia de ordenação ou cancelamento fornecida pela API.

Sucesso pode trazer registros ou nenhum

Com registros retornados, mostre apenas campos disponíveis e identifique o material como histórico. Um comentário não precisa ter título, e uma data ausente deve continuar desconhecida. Descreva a página visível, sem anunciar uma contagem exata quando pagination.relation for gte ou unknown.

Uma resposta vazia bem-sucedida é um resultado diferente. Uma mensagem possível é: Esta solicitação não retornou registros. Ofereça uma mudança deliberada nos termos ou filtros, mantendo a entrada disponível. Não afirme que aquela conversa não existe em lugar nenhum. Uma recuperação vazia bem-sucedida continua custando um crédito.

400, 401 e 402 têm responsáveis diferentes

HTTP 400 indica entrada inválida. Verifique o problema concreto: parâmetro não aceito, página fora do intervalo ou data fora de YYYY-MM-DD são exemplos. Explique o campo que a pessoa pode corrigir quando aplicável e deixe erros de contrato do backend nos diagnósticos do operador.

HTTP 401 significa chave API do serviço ausente ou inválida. Não demonstra que a sessão da pessoa no aplicativo expirou, e essas chaves não têm um mecanismo documentado de expiração programada. O operador verifica a chave salva para este domínio e qualquer regeneração recente. Não peça ao caminhante uma chave ou acesso à conta do serviço.

HTTP 402 significa créditos insuficientes na conta do serviço. A mensagem ao leitor pode indicar que a busca de conversas está temporariamente pausada. O operador pode acessar Chave e créditos e conferir o saldo. Uma nova solicitação é uma ação separada depois de tratar a causa; repetir a antiga não resolve o problema.

429, falha na fonte e entrega incerta

HTTP 429 significa que foi atingido um limite de solicitações. Respeite Retry-After, reduza envios repetidos e permita outra tentativa quando adequado. O limite pode envolver um backend ou uma conta compartilhada, por isso evite culpar um leitor. Não entre em um ciclo ilimitado de tentativas automáticas.

O gateway informa falhas da fonte consultada como HTTP 502. Preserve a consulta e mostre uma opção explícita de tentar novamente sem prometer sucesso. O crédito reservado é devolvido quando a solicitação à fonte falha; a resposta também pode informar conciliação pendente. Se o aplicativo perde a resposta inteira, o resultado da cobrança é incerto: o servidor pode ter concluído com sucesso.

A rota pública /v1/status fornece uma declaração estática do escopo e mostra que seu manipulador HTTP responde. Ela não testa buscas nem certifica a saúde da fonte. Baseie decisões operacionais no resultado real da solicitação. Volte ao Percurso do aplicativo para o roteiro completo ou à nota sobre carregamento, vazio e erro para escolhas de implementação.