Referência de Códigos de Erro da API#

URL base: https://api.ideal.house
Versão: v1
Atualizado: 2026-03-06

📖 Visão geral#

Todas as respostas da API seguem uma estrutura JSON unificada. Quando ocorre um erro, o campo code conterá um código de erro diferente de zero, e o campo message fornecerá uma descrição legível do erro.

Formato de Resposta Unificado

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

✅ Código de Sucesso#

Exemplo

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

❌ Códigos de Erro#

🔧 Erros Gerais#

🔐 Erros de Autenticação#

🛡️ Erros de Moderação de Conteúdo#

💰 Erros de Créditos#

📋 Resumo Completo dos Códigos de Erro#

📦 Exemplos de Resposta de Erro#

1001 — Falha na Solicitação#

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

1003 — Erro Interno do Servidor#

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

1011 — Erro de Parâmetro#

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

5002 — Chave API Inválida#

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

9010 — Moderação de Conteúdo Texto Falhou#

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

9038 — Conteúdo Proibido na Saída#

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

9051 — Créditos Insuficientes#

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

💡 Melhores Práticas para Manipulação de Erros#

1. Sempre verifique o campo code — Não confie apenas nos códigos de status HTTP; inspecione sempre o campo code no corpo da resposta.
2. Trate 1001 de forma dinâmica — Este é um código de erro genérico; o campo message conterá o motivo específico.
3. Retente em caso de 1003 — Erros do lado do servidor geralmente são transitórios; implemente lógica de retry com backoff exponencial.
4. Valide entradas antes de enviar — Evite erros de 1011 validando os campos obrigatórios no cliente antes de fazer a chamada da API.
5. Moderação de conteúdo — Se você receber 9010 ou 9038, revise seu conteúdo conforme a Política de Conteúdo da plataforma antes de reenviar.

© Ideal House AI — Todos os direitos reservados.