Visnea API
Errors
Every error arrives in one JSON envelope: a human-readable error and a machine code. Some codes carry extra fields — described below.
Error envelope
{ "error": string, "code": string }
{ "error": "not enough cherries", "code": "insufficient"}Primary codes
| Code | HTTP | When it happens | What to do |
|---|---|---|---|
unauthorized | 401 | Missing Authorization header, an invalid or revoked key. | Check the key; create a new one in the cabinet if needed. |
insufficient | 402 | Not enough cherries on the balance for the operation. | Top up in the cabinet and retry the request. |
param_unsupported | 400 | A parameter value this model does not support (e.g. a foreign aspect_ratio). Nothing is charged. | Use the allowed values from the response or from the model's form in /v1/models. |
prompt_too_long | 400 | The prompt exceeds the model's limit (max_prompt_chars). Nothing is charged. | Shorten the prompt to limit characters; the limit is in the response. |
content_blocked | 422 | The prompt or message violates the content policy. | Rephrase the request; nothing was charged. |
unavailable | 503 | The model or a subsystem is temporarily unavailable. | Retry later; a different model may work right away. |
Paid but unfinished generations are refunded automatically: a failed status means the cherries are already back on your balance.
Extra fields
param_unsupported adds field and allowed, prompt_too_long adds length and limit:
{ "error": "…", "code": "param_unsupported", "field": "aspect_ratio", "allowed": ["16:9", "9:16", "1:1"]}{ "error": "…", "code": "prompt_too_long", "length": 2450, "limit": 2000}Other codes
| Code | HTTP | When it happens | What to do |
|---|---|---|---|
bad_request | 400 | Invalid JSON or request body. | Check the syntax and Content-Type: application/json. |
no_prompt | 400 | The prompt is empty but the model requires one. | Pass a prompt. |
no_model | 404 | model_id was not found. | Take a current id from /v1/models. |
model_disabled | 400 | The model is disabled in the catalog. | Pick another model from /v1/models. |
not_found | 404 | No generation with this id (or it belongs to another account). | Check the id from the /v1/generate response. |
insufficient_balance | 402 | The insufficient variant used by the chat endpoints. | Top up and retry. |
internal | 500 | Internal service error. | Retry; if it persists, contact support. |