Erros e diagnóstico

Formato

Antes do início da resposta SSE, os erros do gateway usam JSON:

{
  "error": {
    "message": "invalid request",
    "type": "invalid_request_error",
    "param": "temperature",
    "code": "invalid_request_error"
  }
}

param pode ser null. Use code para classificar a causa, não o texto de message. type agrupa erros em authentication_error, invalid_request_error, rate_limit_error ou server_error. O exemplo acima é ilustrativo.

Códigos do gateway

HTTP	error.code	Como agir
400	invalid_request_error	Corrigir JSON, tipos, valores e combinações inválidas
400	unsupported_parameter	Remover o campo fora do subconjunto; verificar param
401	invalid_api_key	Conferir Bearer, chave válida e organização/projeto ativos
403	feature_not_allowed	Verificar permissão de streaming do projeto/modelo
404	model_not_found	Usar um modelo autorizado de /v1/models
404	not_found	Conferir o caminho do endpoint
405	method_not_allowed	Usar o método HTTP correto
413	request_too_large	Reduzir o corpo da requisição, limitado a 1 MiB
429	rate_limit_error	Reduzir taxa e respeitar Retry-After quando enviado
429	concurrency_exceeded	Reduzir chamadas simultâneas e respeitar Retry-After
429	quota_exceeded	Verificar quota e próximo período de liberação
502	backend_error	Falha no caminho de inferência; guardar request-id
503	backend_error	Caminho de inferência indisponível/encerrado sem conclusão válida
503	model_unavailable	Modelo autorizado sem destino elegível/disponível
503	service_unavailable	Configuração/serviço indisponível
503	admission_unavailable	Admissão temporariamente indisponível
503	accounting_unavailable	Contabilização indisponível; guardar request-id
503	quota_unavailable	Verificação de quota indisponível
504	inference_timeout	Prazo do caminho de inferência excedido

A tabela inclui comportamento do código do gateway que pode ser mais detalhado que as respostas genéricas descritas no OpenAPI. Erros do proxy/CDN podem ter outro formato; verifique status e Content-Type antes de tentar decodificar JSON.

Repetição e falhas parciais

Os exemplos não repetem automaticamente o POST de chat. Uma falha de transporte pode ocorrer depois que o processamento começou; repetir pode criar outra requisição e consumir recursos novamente. Não há garantia de idempotência do chat.

Para rejeições HTTP 429, aguarde Retry-After quando fornecido. Se implementar retries, limite tentativas e use espera progressiva com jitter. Após receber conteúdo SSE parcial, preserve o estado de falha e deixe uma nova tentativa ser uma decisão explícita da aplicação.

Durante SSE, um erro pode chegar em data: {"error": {...}} com HTTP ainda 200. O cliente deve verificar o conteúdo de cada evento e a conclusão do stream. Consulte streaming.

Para diagnóstico, informe horário, endpoint, status, error.code e x-nexvra-request-id. Não envie sua API key nem conteúdo confidencial de prompts.