API Error Code Reference#

Base URL: https://api.ideal.house
Version: v1
Updated: 2026-03-06

📖 Overview#

All API responses follow a unified JSON structure. When an error occurs, the code field will contain a non-zero error code, and the message field will provide a human-readable description of the error.

Unified Response Format

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

✅ Success Code#

Example

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

❌ Error Codes#

🔧 General Errors#

🔐 Authentication Errors#

🛡️ Content Moderation Errors#

💰 Credits Errors#

📋 Complete Error Code Summary#

📦 Error Response Examples#

1001 — Request Failed#

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

1003 — Internal Server Error#

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

1011 — Parameter Error#

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

5002 — Invalid API Key#

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

9010 — Text Content Moderation Failed#

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

9038 — Output Prohibited Content#

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

9051 — Insufficient Credits#

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

💡 Best Practices for Error Handling#

1. Always check code — Do not rely solely on HTTP status codes; always inspect the code field in the response body.
2. Handle 1001 dynamically — This is a generic error code; the message field will contain the specific reason.
3. Retry on 1003 — Server-side errors are usually transient; implement exponential backoff retry logic.
4. Validate inputs before sending — Avoid 1011 errors by validating required fields client-side before making the API call.
5. Content moderation — If you receive 9010 or 9038, review your content against the platform's Content Policy before resubmitting.

© Ideal House AI — All rights reserved.