Tratamento de Erros

A Pixapi retorna códigos de status HTTP e códigos de erro legíveis por máquina. Seu aplicativo deve separar erros corrigíveis pelo usuário de falhas de infraestrutura transitórias.

Formato do erro

{
  "error": {
    "code": "model_unavailable",
    "message": "The selected model is temporarily unavailable.",
    "request_id": "req_..."
  }
}

Categorias de tratamento

Categoria	Exemplos	Ação
Erros de requisição	invalid_request, model_not_found	Corrija a validação da requisição.
Erros de autenticação	unauthorized	Solicite uma chave de API válida.
Erros de cobrança	insufficient_credits	Mostre Créditos ou Cobrança.
Erros de política	prompt_rejected	Peça ao usuário para revisar a entrada.
Erros transitórios	rate_limited, model_unavailable	Repita com backoff.

Padrão de repetição

Use backoff exponencial para falhas transitórias.

const delays = [500, 1000, 2000];
for (const delay of delays) {
  const res = await callPixapi();
  if (res.ok) return res;
  if (![429, 500, 503].includes(res.status)) break;
  await new Promise((resolve) => setTimeout(resolve, delay));
}

IDs de requisição

Registre o request_id quando disponível. Inclua-o ao abrir um ticket de suporte para que a equipe possa rastrear uma chamada de modelo com falha sem expor o prompt original a sistemas não relacionados.