Comprender cómo la API informa los errores le ayuda a responder rápidamente y a mantener su integración resiliente. La API de Fit It On clasifica los errores en dos fases distintas:
- Errores a nivel de API: La solicitud fue rechazada inmediatamente antes de que se emitiera un ID de predicción.
- Errores de tiempo de ejecución: La solicitud fue aceptada y se devolvió un ID de predicción, pero la generación falló durante el procesamiento asíncrono.
Errores a Nivel de API
Los errores a nivel de API ocurren de forma síncrona. Cuando realiza una solicitud POST a /v1/run, o una solicitud GET a /v1/status/{id}, el servidor valida la solicitud antes de comenzar cualquier trabajo intensivo en segundo plano.
Si la validación falla, la API devuelve un estado de error HTTP (por ejemplo, 400, 401), y la respuesta JSON contiene un mensaje de error y un code de cadena específico.
{
"error": "Invalid request payload. Expected { model_name, inputs }",
"code": "BadRequest"
}Códigos de Error Estándar
| Código | Error | Causa | Cómo solucionar |
|---|---|---|---|
| 400 | BadRequest | Formato de solicitud no válido o nombre de modelo no compatible | Verifique la estructura JSON, asegúrese de que model_name sea correcto y verifique que se proporcionen todas las inputs requeridas. |
| 401 | UnauthorizedAccess | Clave API no válida o faltante | Verifique que el encabezado Authorization: Bearer YOUR_API_KEY sea correcto y que la clave esté activa. |
| 402 | OutOfCredits | No quedan créditos de API de desarrollador | Recargue sus créditos en el panel de Fit It On antes de reintentar. |
| 403 | Forbidden | Acceso no autorizado a la predicción | Está intentando verificar el estado de una predicción creada por una clave de desarrollador diferente. |
| 404 | NotFound | Predicción no encontrada | Confirme que el ID de predicción es correcto al consultar el endpoint de estado. |
| 413 | PayloadTooLarge | La carga útil excede los límites | Asegúrese de que las imágenes de entrada tengan menos de 25 MB y utilicen resoluciones razonables. |
| 500 | InternalServerError | Error del lado del servidor | Reintente con retroceso. Póngase en contacto con soporte si el problema persiste. |
[!TIP] Reintentos e idempotencia Si encuentra un error a nivel de API, puede reintentar de forma segura la misma carga útil una vez que se resuelva el problema. Debido a que la solicitud fue rechazada inmediatamente, no se dedujeron créditos y el procesamiento duplicado no es un riesgo.
Errores de Tiempo de Ejecución
Los errores de tiempo de ejecución ocurren después de que la API ha aceptado con éxito su solicitud y ha devuelto un ID de predicción.
Debido a que los modelos de generación son altamente asíncronos, descubrirá estos errores al consultar el endpoint /v1/status/{id}. Si un trabajo en segundo plano falla, el endpoint devuelve un HTTP 200 OK (porque la solicitud de consulta en sí fue exitosa), pero el campo status dentro de la carga útil será "failed".
La respuesta incluirá el ID de predicción y un objeto error que detalla lo que salió mal, incluyendo un name categorizado y un message descriptivo.
{
"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"
}Errores Comunes de Tiempo de Ejecución
La mayoría de los problemas de tiempo de ejecución se dividen en un puñado de categorías compartidas en nuestros modelos:
| Categoría | Mensajes de Error Típicos | Cómo solucionar |
|---|---|---|
| Error de Carga de Imagen | No se pudo obtener la imagen, URL de imagen no válida | Asegúrese de que las URL proporcionadas sean de acceso público sin autenticación. Para Base64, asegúrese de que incluya el prefijo de tipo MIME correcto. |
| Validación de Entrada | Resolución de imagen demasiado pequeña, Parámetro requerido faltante | Asegúrese de que sus activos de entrada cumplan con las dimensiones y requisitos mínimos para el modelo específico. |
| Moderación de Contenido | Contenido NSFW detectado, Bloqueo de seguridad activado | Reemplace o ajuste la imagen de entrada o el prompt de texto para cumplir con los filtros de seguridad. |
| Error de Pipeline | Generación fallida, Error del servidor | Ocurrió una falla inesperada en el clúster de GPU. Reintente la solicitud con retroceso. |
[!NOTE] Reembolsos de Créditos por Fallo Las predicciones fallidas no consumen créditos. Si una generación falla durante el tiempo de ejecución (por ejemplo, debido a un
Image Load Erroro unPipeline Error), los créditos deducidos al inicio de la solicitud se reembolsan automáticamente a su saldo de desarrollador.
Errores Específicos del Endpoint
Ciertos modelos tienen reglas de validación estrictas y específicas del flujo de trabajo que se ejecutan durante la generación:
- Control de Pose: Fallará si no se detecta un cuerpo humano en la imagen objetivo.
- Probador Virtual: Fallará si no puede detectar una prenda válida en la imagen de la prenda.
- Generación de Modelo: Fallará si la imagen de referencia facial proporcionada no contiene una cara clara y sin obstrucciones.
Si continúa viendo fallas en tiempo de ejecución después de alinear las entradas con la documentación, póngase en contacto con soporte con su ID de predicción para que podamos investigar.