⚠️ Error Handling & Exceptions

Our API returns structured errors whenever validation fails, credits are depleted, or credentials are invalid.

Standard Error Response

Errors are returned in JSON format. The response body includes a status boolean, the HTTP status code, a descriptive message, and detail information to aid troubleshooting.

Standard Error JSON Schema
{
  "success": false,
  "statusCode": 401,
  "message": "Invalid or revoked API Key.",
  "detail": "Invalid or revoked API Key."
}

Response Status Codes

The VTON service maps execution failures to semantic HTTP status codes.

HTTP Status	Exception Class	Description	Recommended Resolution
400	HTTPException	Request parameters are missing or formatted incorrectly.	Verify fields and types against schemas.
401	InvalidAPIKeyError	Missing, invalid, or revoked X-API-Key header.	Verify key syntax (smd_live_...) and status in dashboard.
403	UnauthorizedError	Requested userId does not match the authenticated API key owner.	Ensure correct matching userId payload.
404	UserNotFoundError / APIKeyNotFoundError	Database lookup failed for the provided user ID or API key.	Verify the target user exists.
422	RequestValidationError	JSON payload schema validation failed (FastAPI standard).	Inspect the detail object to pinpoint validation issues.
501	InsufficientCreditsError	Credit balance is lower than the model credit cost.	Direct the developer to buy credit top-up packages.
500	InternalServerError	An unhandled error occurred within the engine.	Retry the request after a backoff period.