Erros e tentativas

Erros da API REST

Toda recusa da API REST (/api/v1/...) tem o mesmo corpo:

{
  "detail": {
    "code": "training_slot_occupied",
    "message": "One training run at a time per account"
  }
}

Decida pelo detail.code; mostre o detail.message. Alguns erros trazem campos extras, como field para uma configuração recusada, ou successor para um caminho encerrado. Os códigos são estáveis dentro de /api/v1: um código novo pode surgir, e um existente mantém seu significado.

HTTP	code padrão	Significado
400	bad_request	A requisição está malformada de um jeito que o schema não expressa.
401	unauthenticated	Credenciais ausentes, inválidas ou expiradas; a resposta traz WWW-Authenticate: Bearer.
402	insufficient_credits	A conta não consegue pagar por esta operação.
403	forbidden	Autenticado, mas sem permissão.
404	not_found	O recurso não existe para quem chamou.
409	conflict	O estado atual do recurso recusa a operação (por exemplo training_slot_occupied ou project_capability_mismatch).
410	api_version_required	Um caminho sem versão encerrado; detail.successor é o caminho a usar.
413	payload_too_large	O corpo passou do limite.
422	validation_error	A requisição falhou na validação; detail.errors lista cada problema de campo.
429	rate_limited	Requisições demais; respeite o Retry-After quando presente.
503	unavailable	Indisponível no momento (por exemplo training_unavailable); tente mais tarde.

Uma rota pode retornar um código mais específico com o mesmo status, por exemplo training_slot_occupied (409) ou embedding_selection_changed (409). A tabela dá o valor padrão de cada status.

Erros compatíveis com a OpenAI

Falhas geradas depois que uma requisição compatível com OpenAI chega ao handler de inferência usam este envelope legível por máquina, inclusive em /v1/completions:

{
  "error": {
    "message": "This project is archived. Unarchive it in project settings to serve requests.",
    "type": "invalid_request_error",
    "code": "project_archived",
    "param": null
  }
}

As dependências de autenticação e a validação do schema rodam antes desse handler. Essas falhas atualmente usam o formato do FastAPI no nível superior:

{
  "detail": "Invalid or inactive API key"
}

Em erros de validação, detail pode ser uma lista de campos. O cliente deve ler primeiro error.code quando houver error; caso contrário, deve tratar detail como falha de credencial ou schema. Nunca decida pelo texto em inglês.

Códigos estáveis

Código	HTTP	Retry-After	Significado
model_warming	503	sim	O modelo está iniciando ou temporariamente ocupado. Tente após o atraso informado, um número limitado de vezes.
overloaded	503	sim	Reservado; um modelo sobrecarregado hoje responde model_warming.
ambiguous_transport	502	não	A requisição pode ter chegado ao modelo. Não repita às cegas.
upstream_error	502	não	O modelo falhou depois de aceitar a requisição.
model_not_supported	400	não	O modelo base nunca esteve no catálogo deste deployment.
model_deprecated	410	não	A base usada pela requisição ou pelo fine-tune foi aposentada. Treine novamente na base atual.
model_not_found	404	não	Um alias ou job bem formado não pode ser resolvido para este chamador.
invalid_request	400, 413 ou 422	não	Erro determinístico da requisição. Em embeddings, 400 cobre mais de duas entradas, acima do limite de entrada do modelo (512 tokens, ou o comprimento do treino até 2.048) por entrada ou no total, lote não suportado ou dimensões não suportadas; error.param identifica input nos limites de entrada.
insufficient_credits	402	não	A conta não pode pagar ou não tem direito ao modelo.
authentication_error	401	não	O bearer foi verificado, mas não há conta ReOpenly associada.
project_capability_mismatch	409	não	O projeto não expõe a capacidade exigida por esta rota.
capacity_unavailable	503	sim	O modelo de embeddings não pode aceitar a requisição agora: está iniciando ou chegaram mais requisições ao mesmo tempo do que ele atende. Tente após o Retry-After.
artifact_not_ready	503	sim	O modelo de embeddings ainda não está pronto para servir. Tente após o Retry-After.
upstream_validation_error	422	não	O modelo de embeddings retornou uma saída que não passou na validação (malformada, não finita, com tamanho ou ordem errados), por isso ela não foi devolvida.
upstream_ambiguous	502	não	A requisição de embedding pode ter chegado ao modelo; ela não foi repetida. Não repita às cegas.
project_archived	404	não	O projeto é reversível, mas somente leitura até ser restaurado pelo proprietário.
internal_error	500	não	Falha inesperada do servidor. Ao contatar o suporte, informe o trace se existir.

model_deprecated é permanente para aquela base: após o corte para 9B, a produção aposentou as entradas 0.8B, 2B e 4B. Artefatos antigos continuam disponíveis para download, mas serving e publicação de aliases dessa base são bloqueados.

Política de retry

Só repita automaticamente quando a resposta trouxer explicitamente Retry-After. Em embeddings, isso pode ocorrer em capacity_unavailable e artifact_not_ready; em geração de texto, em model_warming. Use um número limitado de tentativas e preserve a identidade da requisição original. O playground v2 da primeira parte faz no máximo três novas tentativas automáticas após a requisição original e depois mantém disponível a ação manual Tentar novamente. Ele nunca repete um erro durante o streaming.

Nunca repita automaticamente:

• ambiguous_transport, pois o modelo pode já ter respondido e a cobrança pode já ter sido registrada;
• upstream_error, pois a admissão já ocorreu;
• insufficient_credits, model_deprecated e project_archived, pois é preciso alterar o estado da conta ou do projeto;
• falhas determinísticas invalid_request.

Falhas durante streaming

Antes do primeiro frame SSE, os erros usam o status HTTP e o corpo JSON normais. Depois que o stream começa, uma falha é enviada como:

data: {"error":{"message":"…","type":"api_error","code":"upstream_error","param":null}}

O servidor fecha o stream sem enviar data: [DONE]. A ausência de [DONE] significa saída incompleta, não uma resposta vazia bem-sucedida.