Saltar para o conteúdo principal

​
Visão Geral

A API Agent-First da LemonData enriquece as respostas de erro com dicas estruturadas que os agentes de IA podem analisar e processar imediatamente — sem buscas na web, sem consultas a documentos, sem adivinhações. Cada resposta de erro inclui campos opcionais como did_you_mean, suggestions, hint, retryable e retry_after dentro do objeto error padrão. Esses campos são retrocompatíveis — clientes que não os utilizam não verão diferença.

​
Campos de Dica de Erro

Todos os campos de dica são extensões opcionais dentro do objeto error:
CampoTipoDescrição
did_you_meanstringNome do modelo correspondente mais próximo
suggestionsarrayModelos recomendados com metadados
alternativesarrayModelos alternativos disponíveis no momento
hintstringOrientação de próximo passo legível por humanos/agentes
retryablebooleanSe tentar a mesma requisição novamente pode ter sucesso
retry_afternumberSegundos para aguardar antes de tentar novamente
balance_usdnumberSaldo atual da conta em USD
estimated_cost_usdnumberCusto estimado da requisição que falhou

​
Exemplos de Códigos de Erro

​
model_not_found (400)

Quando o nome de um modelo não corresponde a nenhum modelo ativo: 
{
  "error": {
    "message": "Model 'gpt5' not found",
    "type": "invalid_request_error",
    "param": "model",
    "code": "model_not_found",
    "did_you_mean": "gpt-4o",
    "suggestions": [
      {"id": "gpt-4o"},
      {"id": "gpt-4o-mini"},
      {"id": "claude-sonnet-4-5"}
    ],
    "hint": "Did you mean 'gpt-4o'? Use GET /v1/models to list all available models."
  }
}
A resolução de did_you_mean utiliza:
  1. Mapeamento de alias estático (de dados de erro de produção)
  2. Correspondência de string normalizada (remove hifens, insensível a maiúsculas/minúsculas)
  3. Correspondência por distância de edição (limite ≤ 3)

​
insufficient_balance (402)

Quando o saldo da conta é muito baixo para o custo estimado: