Pular para o conteúdo principal
Use error.code e o status HTTP para decidir o que fazer, não o texto da mensagem. Todo erro do Phaseo tem o mesmo corpo JSON em todos os endpoints, e o objeto error dele (code, message, type, param) tem o formato que os SDKs compatíveis com a OpenAI leem, então as exceções desses SDKs trazem a mensagem do Phaseo.

Campos presentes em todo erro

Alguns erros acrescentam mais contexto:

Tipos de erro

error.type segue os tipos de erro documentados da OpenAI e é definido a partir do status HTTP: Os erros em /v1/messages usam o mesmo corpo, então os SDKs da Anthropic também encontram error.type e error.message.

Códigos de erro

Repetir os erros certos

Defina um limite de tentativas e um prazo total. Consulte Limites de taxa para ver os cabeçalhos de limite de taxa.

Quando um provedor falha

Quando o Phaseo alcançou um provedor e a solicitação ainda assim falhou, provider_failure_diagnostics traz uma category, uma hint e o provider. Categorias:

Quando um modelo ou endpoint não está disponível

Erros unsupported_model_or_endpoint podem incluir provider_candidate_diagnostics, provider_enablement, missing_pricing_providers e routing_diagnostics. Juntos, eles distinguem um modelo que ainda não está ativo, um modelo que não suporta o endpoint, preços ausentes e restrições de lançamento.

Quando um modelo é aposentado

Um modelo aposentado continua sendo atendido enquanto algum provedor o atender. Quando nenhum o atende mais, as solicitações falham com 410 e model_retired:
model é o modelo que você pediu, retired_at é quando ele foi aposentado (ou null) e replacement_model é o substituto sugerido (ou null). Tentar de novo não ajuda; mude o ID do modelo. Para manter essas solicitações funcionando durante a migração, adicione o substituto à lista models da solicitação ou ative o roteamento de modelos aposentados no espaço de trabalho. Consulte Descontinuação e aposentadoria de modelos.

Erros durante um stream

Se uma solicitação falha antes de o streaming começar, você recebe o corpo de erro JSON acima. Se ela falha no meio do stream, o stream termina com o evento de falha do endpoint, em vez de uma finalização normal: Trate a saída parcial como incompleta e ofereça uma nova tentativa. O frame error do Chat Completions traz o mesmo objeto de erro, com error.type definido a partir do código:
Uma solicitação sem streaming cujo provedor falha no meio do caminho retorna 502 com upstream_stream_failure, e não uma resposta parcial. Consulte Streaming.

Depurar uma solicitação

Envie um objeto debug para receber rastreamentos de roteamento e os payloads do upstream:
trace_level é summary ou full. Os payloads de depuração podem conter o conteúdo da sua solicitação, então use-os apenas em desenvolvimento ou em ambientes rigidamente controlados. Consulte debug. Quando uma solicitação falhar, verifique incidentes na página de status, compare seu payload com a página de referência do endpoint e registre generation_id junto com o endpoint e o modelo. Inclua o generation_id ao entrar em contato com o suporte.
Última modificação em 5 de novembro de 2026