API 오류 코드 참조#

기본 URL: https://api.ideal.house
버전: v1
갱신일: 2026-03-06

📖 개요#

모든 API 응답은 통일된 JSON 구조를 따릅니다. 오류가 발생하면 code 필드에 영이 아닌 오류 코드가 포함되고 message 필드에는 사람이 읽을 수 있는 오류 설명이 제공됩니다.

통일된 응답 형식

{
  "code": 1001,
  "message": "Request failed",
  "data": null
}

✅ 성공 코드#

예제

{
  "code": 0,
  "message": "success",
  "data": { }
}

❌ 오류 코드#

🔧 일반 오류#

🔐 인증 오류#

🛡️ 콘텐츠 검토 오류#

💰 크레딧 오류#

📋 전체 오류 코드 요약#

📦 오류 응답 예제#

1001 — 요청 실패#

{
  "code": 1001,
  "message": "Request failed",
  "data": null
}

1003 — 내부 서버 오류#

{
  "code": 1003,
  "message": "Internal server error",
  "data": null
}

1011 — 매개변수 오류#

{
  "code": 1011,
  "message": "Request parameter error: imageUrl is required",
  "data": null
}

5002 — 유효하지 않은 API 키#

{
  "code": 5002,
  "message": "Invalid API Key",
  "data": null
}

9010 — 텍스트 콘텐츠 검토 실패#

{
  "code": 9010,
  "message": "Text prompt failed content review, contains prohibited content",
  "data": null
}

9038 — 출력에 금지된 콘텐츠 포함#

{
  "code": 9038,
  "message": "Prohibited content",
  "data": null
}

9051 — 크레딧 부족#

{
  "code": 9051,
  "message": "Insufficient coins",
  "data": null
}

💡 오류 처리 권장 사항#

1. 항상 code 확인 — HTTP 상태 코드에만 의존하지 말고 응답 본문의 code 필드를 항상 검사하세요.
2. 1001을 상황에 맞게 처리 — 일반 오류 코드이므로 구체적인 사유는 message 필드에 포함됩니다.
3. 1003이면 재시도 — 서버 측 오류는 일반적으로 일시적입니다. 지수 백오프 재시도 로직을 구현하세요.
4. 전송 전 입력 검증 — API 호출 전에 클라이언트 측에서 필수 필드를 검증하여 1011 오류를 방지하세요.
5. 콘텐츠 검토 — 9010 또는 9038을 받으면 다시 제출하기 전에 플랫폼의 콘텐츠 정책에 따라 콘텐츠를 검토하세요.

© Ideal House AI — 모든 권리 보유.