API & MCP

Erros

Erros têm sempre o mesmo formato: ok: false, um error estável (para o seu código), uma message humana e o requestId.

{
  "ok": false,
  "error": "faixa-nao-atendida",
  "message": "Nenhum kit padrão precificável cobre essa faixa de potência para essa fase. Verifique a cobertura da sua API.",
  "docs": "https://app.ionluz.com.br/docs/api",
  "requestId": "req_9f2c1a7b3d4e5f6a90",
  "kwp": 12.3,
  "fase": "tri"
}

error	HTTP	O que fazer
`chave-invalida`	401	Confira o header `Authorization: Bearer ilz_...`; a chave pode ter sido revogada.
`json`	400	Corpo não é JSON válido. Verifique o `Content-Type: application/json`.
`payload-grande`	413	Corpo passou de 4 KB.
`consumo`	400	`consumoKwhMes` ausente ou ≤ 0.
`consumo-fora-de-faixa`	400	`consumoKwhMes` acima do plausível (1.000.000 kWh/mês). Confira a unidade: o campo é kWh por mês.
`fase-invalida`	422	`fases` não reconhecida. Envie `mono`, `bi` ou `tri` (ou `monofasico`/`bifasico`/`trifasico`, com ou sem acento).
`consentimento-obrigatorio`	400	Gravação (não-preview) sem `consent: true`. Colete o consentimento do titular e reenvie.
`plano-sem-api`	403	Chave válida, mas o plano da conta não inclui API, a API pública é do plano Total + API (R$ 97/mês). Assine em `/plano`.
`chave-de-teste`	403	Recurso que a chave de teste não alcança, como `/v1/proposals` e a ferramenta `get_proposal`. Use a chave viva.
`teto-teste`	429	A chave de teste gastou as 50 chamadas do dia. A cota volta à meia-noite, no horário de Brasília. Sem `Retry-After`, porque a janela não é de segundos.
`proposta-nao-encontrada`	404	Nenhuma proposta com este id nesta conta. Confira o id, ou liste em `/v1/proposals`.
`parametro-invalido`	400	Parâmetro de query fora do aceito (`limit`, `origem`). A resposta traz `parametro` e `aceito` com os valores válidos.
`metodo-nao-permitido`	405	Método HTTP errado (ex.: GET em `/v1/quote`, POST em `/v1/coverage`). A resposta indica o método certo.
`faixa-nao-atendida`	422	Não há kit para essa faixa/fase. Consulte `/v1/coverage`.
`sem-preco-configurado`	422	Sua formação de preço não gerou valor. Revise Preços no painel.
`idempotencia`	422	`Idempotency-Key` reutilizada com corpo diferente. Use uma chave nova.
`em-processamento`	409	Outra requisição com a mesma `Idempotency-Key` ainda está processando. Repita em instantes.
`rate`	429	Muitas requisições. Espere o `Retry-After`.
`teto-leads`	429	Limite absoluto de propostas da conta atingido. Vem sem `Retry-After`, não adianta repetir; fale com o suporte.
`interno`	500	Erro nosso. Repita; se persistir, contate o suporte com o `requestId`.

API v1 · ionluz, orçamentos solares. Dúvidas? Cite o requestId ao escrever para suporte@ionluz.com.br.