API가 오류를 보고하는 방식을 이해하면 신속하게 대응하고 통합의 복원력을 유지하는 데 도움이 됩니다. Fit It On API는 오류를 두 가지 개별 단계로 분류합니다.
- API 수준 오류: 예측 ID가 발급되기 직전에 요청이 즉시 거부되었습니다.
- 런타임 오류: 요청이 수락되고 예측 ID가 반환되었지만 비동기 처리 중에 생성이 실패했습니다.
API 수준 오류
API 수준 오류는 동기적으로 발생합니다. /v1/run에 POST 요청을 하거나 /v1/status/{id}에 GET 요청을 할 때, 서버는 집중적인 백그라운드 작업을 시작하기 전에 요청의 유효성을 검사합니다.
유효성 검사에 실패하면 API는 HTTP 오류 상태(예: 400, 401)를 반환하고, JSON 응답에는 error 메시지와 특정 문자열 code가 포함됩니다.
{
"error": "Invalid request payload. Expected { model_name, inputs }",
"code": "BadRequest"
}표준 오류 코드
| 코드 | 오류 | 원인 | 해결 방법 |
|---|---|---|---|
| 400 | BadRequest | 잘못된 요청 형식 또는 지원되지 않는 모델 이름 | JSON 구조를 확인하고, model_name이 올바른지 확인하며, 필요한 모든 inputs가 제공되었는지 확인합니다. |
| 401 | UnauthorizedAccess | 잘못되었거나 누락된 API 키 | Authorization: Bearer YOUR_API_KEY 헤더가 올바르고 키가 활성 상태인지 확인합니다. |
| 402 | OutOfCredits | 남은 개발자 API 크레딧 없음 | 다시 시도하기 전에 Fit It On 대시보드에서 크레딧을 충전하세요. |
| 403 | Forbidden | 예측에 대한 무단 액세스 | 다른 개발자 키로 생성된 예측의 상태를 확인하려고 시도하고 있습니다. |
| 404 | NotFound | 예측을 찾을 수 없음 | 상태 엔드포인트를 폴링할 때 예측 ID가 올바른지 확인합니다. |
| 413 | PayloadTooLarge | 페이로드가 제한을 초과함 | 입력 이미지가 25MB 미만이고 합리적인 해상도를 사용하는지 확인합니다. |
| 500 | InternalServerError | 서버 측 오류 | 백오프를 사용하여 다시 시도합니다. 문제가 지속되면 지원팀에 문의하세요. |
[!TIP] 재시도 및 멱등성 API 수준 오류가 발생하면 문제가 해결된 후 동일한 페이로드를 안전하게 다시 시도할 수 있습니다. 요청이 즉시 거부되었으므로 크레딧이 차감되지 않았으며 중복 처리의 위험이 없습니다.
런타임 오류
런타임 오류는 API가 요청을 성공적으로 수락하고 예측 ID를 반환한 후에 발생합니다.
생성 모델은 비동기 방식이므로, /v1/status/{id} 엔드포인트를 폴링하는 동안 이러한 오류를 발견하게 됩니다. 백그라운드 작업이 실패하면 엔드포인트는 HTTP 200 OK를 반환하지만(폴링 요청 자체는 성공했으므로), 페이로드 내의 status 필드는 "failed"가 됩니다.
응답에는 예측 ID와 함께 발생한 문제를 자세히 설명하는 error 객체가 포함되며, 여기에는 분류된 name과 설명적인 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"
}일반적인 런타임 오류
대부분의 런타임 문제는 모델 전반에 걸쳐 몇 가지 공통된 범주에 속합니다.
| 범주 | 일반적인 오류 메시지 | 해결 방법 |
|---|---|---|
| 이미지 로드 오류 | Failed to fetch image, Invalid image URL | 제공된 URL이 인증 없이 공개적으로 액세스 가능한지 확인합니다. Base64의 경우 올바른 MIME 유형 접두사가 포함되어 있는지 확인합니다. |
| 입력 유효성 검사 | Image resolution too small, Missing required parameter | 입력 자산이 특정 모델의 최소 치수 및 요구 사항을 충족하는지 확인합니다. |
| 콘텐츠 조정 | NSFW content detected, Safety block triggered | 안전 필터를 준수하도록 입력 이미지 또는 텍스트 프롬프트를 교체하거나 조정합니다. |
| 파이프라인 오류 | Generation failed, Server error | GPU 클러스터에서 예기치 않은 오류가 발생했습니다. 백오프를 사용하여 요청을 다시 시도합니다. |
[!NOTE] 실패 시 크레딧 환불 실패한 예측은 크레딧을 소비하지 않습니다. 런타임 중에 생성에 실패하면(예:
Image Load Error또는Pipeline Error로 인해) 요청 시작 시 차감된 크레딧은 개발자 잔액으로 자동으로 환불됩니다.
엔드포인트별 오류
특정 모델에는 생성 중에 실행되는 엄격한 워크플로별 유효성 검사 규칙이 있습니다.
- 포즈 제어: 대상 이미지에서 인체가 감지되지 않으면 실패합니다.
- 가상 착용: 의류 이미지에서 유효한 의류를 감지할 수 없으면 실패합니다.
- 모델 생성: 제공된 얼굴 참조 이미지에 명확하고 가려지지 않은 얼굴이 포함되어 있지 않으면 실패합니다.
문서에 따라 입력을 조정한 후에도 런타임 오류가 계속 발생하면 예측 ID와 함께 지원팀에 문의하여 조사할 수 있도록 해주십시오.