Erros, limites e novas tentativas

Toda API da Felo retorna um corpo de erro JSON com um código de erro estável e um request ID. Leia primeiro o status HTTP, depois o código e, por fim, a mensagem.

Envelope de erro

As respostas de produção atuais usam o status HTTP como status:

{
  "status": 401,
  "code": "UNAUTHORIZED",
  "message": "Invalid API Key",
  "request_id": "202610221444486982113280416060637185"
}

Alguns exemplos antigos de endpoints usam status: "error" e uma string de código diferente. Decida com base no status HTTP e em code, não no texto exato de message.

Códigos comuns

As referências de endpoint listam os códigos específicos daquele endpoint. Comece pelos erros da Chat API ou pela referência do endpoint que você está chamando.

Endpoints de geração de modelos

POST /api/v1/images/generations e POST /api/v1/videos/generations retornam erros no nível do endpoint no envelope da OpenAI, em vez do envelope acima:

{
  "error": {
    "message": "Model kind does not match this generation endpoint",
    "type": "invalid_request_error",
    "param": null,
    "code": "model_kind_mismatch"
  }
}

O request ID fica no cabeçalho de resposta X-Request-Id, não no corpo. Uma requisição rejeitada não cria uma tarefa. Depois que uma tarefa existe, a maioria das falhas chega como status terminal na tarefa em uma resposta 200, e não como erro HTTP: verifique se status é failed ou interrupted e então leia error.message. Consulte Geração de imagens e Tarefas assíncronas.

Request IDs

Os corpos de erro da Felo incluem request_id. Registre-o no log junto com o endpoint, o status HTTP, o código de erro, o ID do modelo e o ID da tarefa. Nunca registre a chave de API completa.

A Model API também aceita um cabeçalho de requisição opcional X-Request-Id. Quando você envia um, ele é devolvido para fins de diagnóstico, o que permite correlacionar seus próprios logs com uma requisição. Se você não enviar um, use o request_id retornado.

Limites de requisições

/v2/chat é o único endpoint da Felo com limites de requisições documentados e aplicados:

• Por chave de API, janela de 1 minuto.
• Por usuário, janela de 1 minuto.
• Por usuário, janela de 1 hora.

Usuários com uma assinatura Felo paga efetiva, incluindo assinaturas empresariais, estão isentos e não recebem cabeçalhos X-RateLimit-*. Se o status da assinatura não puder ser verificado, os limites continuam valendo.

Os demais endpoints /v2/** não têm limites de requisições aplicados no momento. Requisições à Model API ainda podem ser limitadas pelo provedor upstream, o que pode aparecer como um 429.

Não codifique limites numéricos. Leia os cabeçalhos de cada resposta.

Política de novas tentativas

Loop recomendado:

1. Tente novamente apenas requisições idempotentes ou seguras de repetir.
2. Use backoff exponencial: comece em cerca de 1 segundo, dobre a cada tentativa e limite a 30 segundos.
3. Adicione jitter aleatório para que os clientes não tentem novamente em sincronia.
4. Pare após um número pequeno de tentativas e exponha o erro.
5. Em um 429, respeite o Retry-After em vez do seu próprio intervalo.

Sequência de depuração

1. Verifique se a chave está presente e não foi revogada.
2. Chame GET /api/v1/models com a mesma chave para confirmar a autenticação.
3. Envie a menor requisição válida para o endpoint de destino.
4. Adicione streaming, ferramentas ou entradas grandes um de cada vez.
5. Para trabalho assíncrono, verifique o status da tarefa antes de reenviar.

Relacionados

• Autenticação
• Canais e roteamento de provedores
• Tarefas assíncronas
• Solução de problemas