Understanding how the API reports errors helps you respond quickly and keep your integration resilient. The Fit It On API categorizes errors into two distinct phases:
- API-level errors: The request was rejected immediately before a prediction ID was issued.
- Runtime errors: The request was accepted and a prediction ID was returned, but the generation failed during asynchronous processing.
API-Level Errors
API-level errors occur synchronously. When you make a POST request to /v1/run, or a GET request to /v1/status/{id}, the server validates the request before beginning any intensive background work.
If validation fails, the API returns an HTTP error status (e.g., 400, 401), and the JSON response contains an error message and a specific string code.
{
"error": "Invalid request payload. Expected { model_name, inputs }",
"code": "BadRequest"
}Standard Error Codes
| Code | Error | Cause | How to fix |
|---|---|---|---|
| 400 | BadRequest | Invalid request format or unsupported model name | Check the JSON structure, ensure model_name is correct, and verify all required inputs are provided. |
| 401 | UnauthorizedAccess | Invalid or missing API key | Verify the Authorization: Bearer YOUR_API_KEY header is correct and the key is active. |
| 402 | OutOfCredits | No developer API credits remaining | Refill your credits in the Fit It On dashboard before retrying. |
| 403 | Forbidden | Unauthorized access to prediction | You are attempting to check the status of a prediction created by a different developer key. |
| 404 | NotFound | Prediction not found | Confirm the prediction ID is correct when polling the status endpoint. |
| 413 | PayloadTooLarge | Payload exceeds limits | Ensure input images are under 25MB and use reasonable resolutions. |
| 500 | InternalServerError | Server-side error | Retry with backoff. Contact support if the issue persists. |
[!TIP] Retries and idempotency If you encounter an API-level error, you can safely retry the exact same payload once the issue is resolved. Because the request was rejected immediately, no credits were deducted and duplicate processing is not a risk.
Runtime Errors
Runtime errors occur after the API has successfully accepted your request and returned a prediction ID.
Because generation models are heavily asynchronous, you will discover these errors while polling the /v1/status/{id} endpoint. If a background job fails, the endpoint returns an HTTP 200 OK (because the polling request itself was successful), but the status field inside the payload will be "failed".
The response will include the prediction ID and an error object detailing what went wrong, including a categorized name and a descriptive message.
{
"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"
}Common Runtime Errors
Most runtime issues fall into a handful of shared categories across our models:
| Category | Typical Error Messages | How to fix |
|---|---|---|
| Image Load Error | Failed to fetch image, Invalid image URL | Ensure provided URLs are publicly accessible without authentication. For Base64, ensure it includes the correct MIME-type prefix. |
| Input Validation | Image resolution too small, Missing required parameter | Ensure your input assets meet the minimum dimensions and requirements for the specific model. |
| Content Moderation | NSFW content detected, Safety block triggered | Replace or adjust the input image or text prompt to comply with safety filters. |
| Pipeline Error | Generation failed, Server error | An unexpected failure occurred in the GPU cluster. Retry the request with backoff. |
[!NOTE] Credit Refunds on Failure Failed predictions do not consume credits. If a generation fails during runtime (e.g., due to an
Image Load Erroror aPipeline Error), the credits deducted at the start of the request are automatically refunded back to your developer balance.
Endpoint-Specific Errors
Certain models have strict, workflow-specific validation rules that run during generation:
- Pose Control: Will fail if no human body is detected in the target image.
- Virtual Try-On: Will fail if it cannot detect a valid garment in the garment image.
- Model Generation: Will fail if the provided face reference image does not contain a clear, unobstructed face.
If you continue to see runtime failures after aligning inputs with the documentation, please contact support with your prediction ID so we can investigate.