Tratamento de Erros | Developer API

Entenda como a API Fit It On reporta erros, incluindo falhas no nível da API e erros de tempo de execução assíncronos.

Compreender como a API reporta erros ajuda você a responder rapidamente e manter sua integração resiliente. A API Fit It On categoriza os erros em duas fases distintas:

Erros no nível da API: A requisição foi rejeitada imediatamente antes da emissão de um ID de previsão.
Erros de tempo de execução: A requisição foi aceita e um ID de previsão foi retornado, mas a geração falhou durante o processamento assíncrono.

Erros no Nível da API

Erros no nível da API ocorrem de forma síncrona. Ao fazer uma requisição POST para /v1/run, ou uma requisição GET para /v1/status/{id}, o servidor valida a requisição antes de iniciar qualquer trabalho intensivo em segundo plano.

Se a validação falhar, a API retorna um status de erro HTTP (por exemplo, 400, 401), e a resposta JSON contém uma mensagem de error e um code de string específico.

{
  "error": "Invalid request payload. Expected { model_name, inputs }",
  "code": "BadRequest"
}

Códigos de Erro Padrão

Código	Erro	Causa	Como corrigir
400	Requisição Inválida	Formato de requisição inválido ou nome de modelo não suportado	Verifique a estrutura JSON, certifique-se de que `model_name` está correto e verifique se todos os `inputs` necessários foram fornecidos.
401	Acesso Não Autorizado	Chave de API inválida ou ausente	Verifique se o cabeçalho `Authorization: Bearer YOUR_API_KEY` está correto e se a chave está ativa.
402	Sem Créditos	Nenhum crédito de API de desenvolvedor restante	Recarregue seus créditos no painel Fit It On antes de tentar novamente.
403	Proibido	Acesso não autorizado à previsão	Você está tentando verificar o status de uma previsão criada por uma chave de desenvolvedor diferente.
404	Não Encontrado	Previsão não encontrada	Confirme se o ID da previsão está correto ao consultar o endpoint de status.
413	Payload Muito Grande	Payload excede os limites	Certifique-se de que as imagens de entrada tenham menos de 25MB e usem resoluções razoáveis.
500	Erro Interno do Servidor	Erro do lado do servidor	Tente novamente com backoff. Entre em contato com o suporte se o problema persistir.

[!TIP] Tentativas e idempotência Se você encontrar um erro no nível da API, pode tentar novamente com segurança o mesmo payload exato assim que o problema for resolvido. Como a requisição foi rejeitada imediatamente, nenhum crédito foi deduzido e o processamento duplicado não é um risco.

Erros de Tempo de Execução

Erros de tempo de execução ocorrem depois que a API aceitou com sucesso sua requisição e retornou um ID de previsão.

Como os modelos de geração são altamente assíncronos, você descobrirá esses erros ao consultar o endpoint /v1/status/{id}. Se um trabalho em segundo plano falhar, o endpoint retorna um HTTP 200 OK (porque a própria requisição de consulta foi bem-sucedida), mas o campo status dentro do payload será "failed".

A resposta incluirá o ID da previsão e um objeto error detalhando o que deu errado, incluindo um name categorizado e uma message descritiva.

{
  "id": "123e4567-e89b-12d3-a456-426614174000",
  "status": "failed",
  "output": null,
  "error": {
    "name": "ImageLoadError",
    "message": "Failed to load input image: URL returned 404"
  },
  "created_at": "2024-05-15T12:00:00Z",
  "updated_at": "2024-05-15T12:00:10Z"
}

Erros Comuns de Tempo de Execução

A maioria dos problemas de tempo de execução se enquadra em algumas categorias compartilhadas em nossos modelos:

Categoria	Mensagens de Erro Típicas	Como corrigir
Erro de Carregamento de Imagem	`Falha ao buscar imagem`, `URL de imagem inválida`	Certifique-se de que as URLs fornecidas sejam publicamente acessíveis sem autenticação. Para Base64, certifique-se de que inclua o prefixo de tipo MIME correto.
Validação de Entrada	`Resolução da imagem muito pequena`, `Parâmetro obrigatório ausente`	Certifique-se de que seus ativos de entrada atendam às dimensões mínimas e aos requisitos para o modelo específico.
Moderação de Conteúdo	`Conteúdo NSFW detectado`, `Bloqueio de segurança acionado`	Substitua ou ajuste a imagem de entrada ou o prompt de texto para cumprir os filtros de segurança.
Erro de Pipeline	`Geração falhou`, `Erro do servidor`	Ocorreu uma falha inesperada no cluster de GPU. Tente novamente a requisição com backoff.

[!NOTE] Reembolso de Créditos em Caso de Falha Previsões falhas não consomem créditos. Se uma geração falhar durante o tempo de execução (por exemplo, devido a um Image Load Error ou um Pipeline Error), os créditos deduzidos no início da requisição são automaticamente reembolsados para o seu saldo de desenvolvedor.

Erros Específicos de Endpoint

Certos modelos possuem regras de validação rigorosas e específicas do fluxo de trabalho que são executadas durante a geração:

Controle de Pose: Falhará se nenhum corpo humano for detectado na imagem alvo.
Experimentação Virtual: Falhará se não conseguir detectar uma peça de vestuário válida na imagem da peça.
Geração de Modelo: Falhará se a imagem de referência facial fornecida não contiver um rosto claro e desobstruído.

Se você continuar a ver falhas de tempo de execução após alinhar as entradas com a documentação, entre em contato com o suporte com seu ID de previsão para que possamos investigar.