> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gengen.farm/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> Handle GENGEN API error responses.

GENGEN errors use a stable JSON envelope:

```json theme={"dark"}
{
  "error_code": "gengen.model_required",
  "error_params": {
    "field": "model"
  },
  "error": "A model is required"
}
```

| Field          | Type   | Description                     |
| -------------- | ------ | ------------------------------- |
| `error_code`   | string | Stable machine-readable code    |
| `error_params` | object | Optional structured context     |
| `error`        | string | Optional human-readable message |

## Common status codes

| HTTP status | Meaning                                                        |
| ----------- | -------------------------------------------------------------- |
| `400`       | Invalid JSON, query parameters, model, mode, or provider input |
| `401`       | Missing or invalid API key                                     |
| `402`       | Insufficient available balance                                 |
| `403`       | Revoked, expired, or unauthorized API key                      |
| `404`       | The task does not exist in the current workspace               |
| `501`       | The selected provider does not support the operation           |
| `5xx`       | GENGEN or an upstream provider could not complete the request  |

## Handling errors

* Branch on `error_code`, not the message text.
* Log the HTTP status, `error_code`, and request correlation data without logging API keys.
* Retry transient `5xx` and rate-limit responses with exponential backoff and jitter.
* Fix `4xx` request errors before retrying.
* Treat task-not-found responses as non-disclosing. The retrieve endpoint does not reveal tasks that are inaccessible to the current API key.

## Provider error codes

When a response includes a BytePlus ModelArk error code, search the
[provider error reference](/help/provider-errors) for its description. Continue to use the GENGEN
`error_code` and HTTP status as the stable values in application logic.