# Errors

Errors look like `{"error": {"type", "code", "message", "param"?, "docs_url", "request_id"}}`. No error is ever charged.

| HTTP | Code | What to do |
|---|---|---|
| 400 | <a id="missing_param"></a>`missing_param` | A required field (`model`, `input`, or a model option like `labels`) is missing. `param` names it. |
| 400 | <a id="invalid_param"></a>`invalid_param` | An option has the wrong type or is out of range. The message says the allowed values. |
| 400 | <a id="unknown_param"></a>`unknown_param` | The model has no option by that name (often a typo). The message lists the valid options. |
| 400 | <a id="invalid_input"></a>`invalid_input` | `input` isn't the right kind (e.g. an array for a model that takes one input). |
| 400 | <a id="empty_input"></a>`empty_input` | An input text is empty or only whitespace. |
| 400 | <a id="invalid_json"></a>`invalid_json` | The body isn't valid JSON. |
| 400 | <a id="invalid_schema"></a>`invalid_schema` | Mold's `schema` isn't a usable JSON Schema object. |
| 400 | <a id="unsupported_image"></a>`unsupported_image` / `unsupported_audio` | We couldn't decode the file. |
| 400 | <a id="input_unreachable"></a>`input_unreachable` | We couldn't download the URL (DNS, timeout, HTTP error, or a private address). |
| 401 | <a id="missing_api_key"></a>`missing_api_key` | Send `Authorization: Bearer gwl_...`. |
| 401 | <a id="invalid_api_key"></a>`invalid_api_key` | The key was revoked, expired or mistyped. Create a new one. |
| 402 | <a id="insufficient_balance"></a>`insufficient_balance` | Add credit at `add_credit_url` or turn on auto top-up, then retry. |
| 402 | <a id="monthly_cap_reached"></a>`monthly_cap_reached` | The account's monthly cap is reached. Raise it in billing settings. |
| 402 | <a id="key_limit_reached"></a>`key_limit_reached` | This key's monthly limit is reached. Raise it or use another key. |
| 403 | <a id="model_not_allowed"></a>`model_not_allowed` | This key is restricted to other models. |
| 404 | <a id="model_not_found"></a>`model_not_found` | Check the id against `GET /v1/models`. |
| 409 | <a id="idempotency_key_reused"></a>`idempotency_key_reused` | The same Idempotency-Key was sent with a different body. |
| 413 | <a id="input_too_large"></a>`input_too_large` | The text or file is over the model's limit (on its page). Split it. |
| 429 | <a id="rate_limited"></a>`rate_limited` | Wait for `Retry-After` seconds, or batch inputs into fewer requests. |
| 500 | <a id="internal_error"></a>`internal_error` | Our bug. Retry once; write to hello@greatwork.company with the `request_id` if it repeats. |
| 502 | <a id="model_error"></a>`model_error` | The model failed on this specific input. Retrying the same input usually fails the same way. |
| 503 | <a id="busy"></a>`busy` / `engine_unavailable` | Every worker is busy or restarting. Retry with backoff (1 s, 2 s, 4 s). |
