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
}

Field	Type	Description
`code`	`integer`	`0` = success; any other value indicates an error
`message`	`string`	Human-readable error description
`data`	`any`	Response payload; `null` on error

✅ Success Code

Code	Name	Description
`0`	`SUCCESS`	Request succeeded

Example

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

❌ Error Codes

🔧 General Errors

Code	Name	Description	Suggested Action
`1001`	`FAILED`	Request failed (generic error)	Check the `message` field for specific details
`1003`	`INTERNAL_ERROR`	Internal server error	Retry the request after a short delay; contact support if it persists
`1011`	`PARAM_ERROR`	Request parameter error	Verify all required parameters are provided and correctly formatted

🔐 Authentication Errors

Code	Name	Description	Suggested Action
`5002`	`API_KEY_INVALID`	Invalid or missing API Key	Ensure the `APIKEY` header is included and the value is correct

🛡️ Content Moderation Errors

Code	Name	Description	Suggested Action
`9010`	`SCAN_TEXT_ERROR`	Text prompt failed content review — contains prohibited content	Modify the prompt to remove any sensitive or illegal content
`9038`	`PROHIBITED_CONTENT`	Generated output image contains prohibited content	Adjust prompt/style/inputs and retry

💰 Credits Errors

Code	Name	Description	Suggested Action
`9051`	`COINS_NOT_ENOUGH`	Insufficient coins / credits	Top up your account credits and retry

📋 Complete Error Code Summary

Code	Name	Description
`0`	`SUCCESS`	Request succeeded
`1001`	`FAILED`	Request failed (generic)
`1003`	`INTERNAL_ERROR`	Internal server error
`1011`	`PARAM_ERROR`	Request parameter error
`5002`	`API_KEY_INVALID`	Invalid API Key
`9010`	`SCAN_TEXT_ERROR`	Text prompt contains prohibited content
`9038`	`PROHIBITED_CONTENT`	Generated output image contains prohibited content
`9051`	`COINS_NOT_ENOUGH`	Insufficient coins / credits

📦 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

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