Estrutura de resposta e códigos de erro da Open API do HappyOyster, incluindo códigos de negócio, cenários típicos e sugestões de tratamento.
Este documento descreve a estrutura de resposta e os códigos de erro da Open API do HappyOyster. Aplica-se a todos os endpoints da Open API dos modelos Adventure, Directing e Acting.
Depois que uma solicitação passa pela autenticação do gateway (tanto para sucesso quanto para erros de negócio), a resposta sempre retorna HTTP 200 com a seguinte estrutura JSON como corpo:
Falhas na camada de gateway, como verificação de AK, assinatura ou timestamp, são rejeitadas diretamente, portanto, essas respostas não seguem esta estrutura e geralmente são retornadas com um código de status HTTP 4xx / 5xx — veja Código de erro.
O acesso entre modelos não revela se o recurso existe: os endpoints de World retornam
Ao consultar o status da Travel ou a lista de Travels, itens com
Qualquer
Estrutura da resposta
Depois que uma solicitação passa pela autenticação do gateway (tanto para sucesso quanto para erros de negócio), a resposta sempre retorna HTTP 200 com a seguinte estrutura JSON como corpo:
| Campo | Tipo | Descrição |
|---|---|---|
code | integer | Código de retorno de negócio. 0 significa sucesso; um valor diferente de0 significa um erro de negócio — veja a lista de códigos de erro abaixo. |
message | string | null | Mensagem de erro legível por humanos. null quando code=0. |
data | object | null | Payload de negócio. Em caso de sucesso, contém o objeto de resposta específico do endpoint; em caso de erro, geralmente null. |
Lista de códigos de erro
| código | Descrição | Cenários típicos e tratamento |
|---|---|---|
0 | Success | Solicitação bem-sucedida; leia data. |
400000 | Parâmetros de solicitação inválidos | mode não corresponde ao modelo atual; prompt ou firstFrameImage está ausente; prompt é muito longo; creationModel / uploadMode / resolution / aspectRatio / perspective tem um valor ilegal; o formato da imagem ou do ID criptografado é inválido. Corrija os parâmetros conforme a documentação da API e tente novamente. |
400001 | Falha ao buscar ou armazenar URL da imagem | A URL da imagem do primeiro quadro ou de referência está inacessível ou expirada. Verifique a acessibilidade e a validade da URL e tente criar o Mundo novamente. |
401010 | ticket inválido ou expirado | Entrar na travel (enter-travel). Chame get-travel-credential novamente para obter um novo ticket. |
401011 | ticket já usado | Entrar na travel. O ticket é de uso único; obtenha um novo. |
403001 | O Mundo não existe, foi excluído, não pertence a você ou não pertence ao modelo atual | Consulta, troca de credenciais, entrada na viagem e filtragem de listas. Na exclusão, este código é retornado apenas para IDs entre contas, entre workspaces ou entre modelos; um ID já inexistente na mesma conta retorna code=0, deleted=false. |
403002 | O Mundo não está ready ou indisponível | Troca de credenciais, entrar na travel. Consulte o status da compilação até ready antes de operar. |
403003 | Este endpoint permite apenas a API Key primária | Gerenciamento de Mundo, lista de Travel, artefatos, etc. Chame com a API Key primária (começa com sk-). |
403004 | O conteúdo de entrada falhou na política de segurança de conteúdo | Criar Mundo, enviar instruct. Ajuste o conteúdo de texto e tente novamente. |
403005 | A imagem de entrada falhou na verificação de direitos autorais ou propriedade intelectual | Criar Mundo. Substitua por uma imagem compatível e tente novamente. |
403007 | Cota de recurso ou serviço não habilitada | Criar, troca de credenciais, entrar na travel. Confirm se a capacidade correspondente do modelo está habilitada. |
403008 | Configuração de capacidade temporariamente indisponível | Criação, troca de credenciais, entrada na viagem. Tente novamente mais tarde ou entre em contato com o provedor de serviços para aumentar a capacidade. |
404000 | A viagem não existe, não pertence a você, não pertence ao modelo atual ou não possui artefatos disponíveis | Consulta de status da Travel, controle, encerramento, consulta de artefatos. |
409000 | A solicitação entra em conflito com o estado atual do recurso | Endpoints de controle como pausar, retomar, encerrar e instruir; também retornado ao chamar um endpoint que um modelo não suporta. |
429001 | A concorrência para a especificação atual está cheia | Entrar na viagem. Tente novamente mais tarde ou aumente a especificação de concorrência. |
429002 | Capacidade disponível insuficiente | Entrar na travel. Tente novamente mais tarde. |
500000 | Erro interno do sistema | Exceções não classificadas; também podem ser retornadas ao chamar um endpoint não suportado (por exemplo, rewind em alguns modelos). |
500001 | Falha ao alocar recursos de streaming | Entrar na travel. Tente novamente mais tarde. |
code=403001 e os endpoints de Travel retornam code=404000.
errorCode de falha da Travel
Ao consultar o status da Travel ou a lista de Travels, itens com status=failed carregam adicionalmente o campo estruturado errorCode e uma descrição em inglês errorMessage (consulte a documentação da API correspondente para a estrutura de resposta de falha). O texto de errorMessage para o mesmo errorCode pode diferir entre os endpoints de consulta e a resposta de Encerrar Travel; faça a ramificação com base em errorCode, não em errorMessage.
| errorCode | errorMessage | Descrição |
|---|---|---|
TRAVEL_SESSION_INIT_FAILED | Failed to allocate inference resources. | A sessão de inferência falhou ao inicializar ao entrar na travel, geralmente devido a recursos de inferência insuficientes |
TRAVEL_NO_STREAM_AUTO_END | No video stream was received before timeout. | O cliente não recebeu o stream antes do tempo limite; encerre a Travel passando failCode na solicitação de Encerrar Travel |
TRAVEL_STREAM_CREATE_FAILED | Failed to create the video stream. | Falha ao criar o canal de streaming |
CONTENT_VIDEO_MODERATION_REJECTED | Something went wrong. | A imagem da experiência foi interrompida pela política de segurança de conteúdo |
TRAVEL_RUNTIME_FAILED | The experience was interrupted by a runtime error. | Outras falhas de tempo de execução, ou o servidor não registrou um motivo específico |
errorCode não listado pode ser tratado como uma falha desconhecida.