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 de nível de 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 de Nível de API

Erros de nível de 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	BadRequest	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 são fornecidos.
401	UnauthorizedAccess	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	OutOfCredits	Sem créditos de API de desenvolvedor restantes	Recarregue seus créditos no painel do Fit It On antes de tentar novamente.
403	Forbidden	Acesso não autorizado à previsão	Você está tentando verificar o status de uma previsão criada por uma chave de desenvolvedor diferente.
404	NotFound	Previsão não encontrada	Confirme se o ID da previsão está correto ao consultar o endpoint de status.
413	PayloadTooLarge	Payload excede os limites	Certifique-se de que as imagens de entrada tenham menos de 25MB e usem resoluções razoáveis.
500	InternalServerError	Erro do lado do servidor	Tente novamente com backoff. Entre em contato com o suporte se o problema persistir.

[!TIP] Retentativas e idempotência Se você encontrar um erro de nível de 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	`Failed to fetch image`, `Invalid image URL`	Certifique-se de que as URLs fornecidas sejam publicamente acessíveis sem autenticação. Para Base64, certifique-se de que inclua o prefixo MIME-type correto.
Validação de Entrada	`Image resolution too small`, `Missing required parameter`	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	`NSFW content detected`, `Safety block triggered`	Substitua ou ajuste a imagem de entrada ou o prompt de texto para cumprir os filtros de segurança.
Erro de Pipeline	`Generation failed`, `Server error`	Uma falha inesperada ocorreu 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 ao 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 Poses: 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.