# Errors

From the Lero API docs: https://lero.studio/docs/en#erros. Everything in one file: https://lero.studio/docs/en/llms-full.txt.

Every error comes back as JSON, with a stable code in the `erro` field and a message in Portuguese. Handle errors by `erro`, never by the `mensagem` text. Speech and transcription errors also carry `pedido` and, when a field is wrong, `campo`.

```json
{"erro": "sem_credito", "mensagem": "Os créditos da conta acabaram.", "pedido": "3f9c1e0a7b2d4c6e8a1b3d5f7e9c0a2b"}
```

| status | erro | when |
|---|---|---|
| 400 | `texto_invalido` | The text is empty, longer than 500 characters, or the voice did not accept it (emojis and symbols). |
| 400 | `voz_invalida` | Unknown voice. Use `rio`, `sp` or `niteroi`. |
| 400 | `audio_invalido` | Transcription: the file is empty, has no readable audio, or the format is not supported. |
| 400 | `url_invalida` | Transcription: `url` is not a public https link, did not answer 200, or could not be downloaded. |
| 400 | `formato_invalido` | Transcription: `formato` is not `json`, `texto`, `srt` or `vtt`. |
| 400 | `idioma_invalido` | Transcription: `idioma` is not `pt-BR`. |
| 400 | `modelo_invalido` | `model` is not `Lero v1`. |
| 400 | `pedido_invalido` | The body is not JSON. On transcription: the body is neither multipart nor JSON, or it has neither `audio` nor `url`, or both. |
| 401 | `sem_chave` | No key in the request. |
| 401 | `chave_invalida` | The key is wrong or was revoked. |
| 401 | `chave_vencida` | The key expired. |
| 402 | `sem_credito` | The account credits do not cover the request. On transcription, the JSON carries `custo` (the credits the audio needs) and `saldo`. |
| 402 | `teto_da_chave` | The key reached its monthly credit cap. |
| 403 | `plano` | The account is not on a plan with the API (Creator or Dev). |
| 403 | `escopo` | The key does not have the Fala scope (it covers speech and transcription). |
| 403 | `bloqueado` | The account is blocked. |
| 413 | `audio_grande` | Transcription: the file in the body is over 4 MB (send it by `url`) or the one at `url` is over 500 MB. |
| 413 | `audio_longo` | Transcription: the audio is longer than 2 h. |
| 429 | `muitos_pedidos` | More than 60 requests per minute on the account. Wait for `Retry-After`. |
| 429 | `simultaneas` | The plan is already at its limit of concurrent requests (Creator 5, Dev 10). Wait for one to finish. |
| 429 | `ocupado` | The voice or the transcription is busy. Wait for `Retry-After`. |
| 503 | `carregando` | The voice is starting up. Wait for `Retry-After`. |
| 503 | `motor_desligado` | The voice or the transcription is offline. Wait for `Retry-After`. |
| 502 | `falhou` | Speech generation or transcription failed. Try again. |
| 504 | `demorou` | Speech generation or transcription timed out. Try again. |
| 500 | `interno` | An error on our side. Try again; if it persists, send us the `X-Pedido-Id`. |
| 400 | `oferta_invalida` | The SDP offer is missing, does not start with `v=0`, or is longer than 20,000 characters. |
| 400 | `versao_invalida` | `versao` is not in the `GET /v1/agents` list for your key. |
| 400 | `llm_invalido` | `llm` is not in the `GET /v1/agents` list. |
| 400 | `roteiro_invalido` | A custom agent field is over its limit. The field name comes in `campo`. |
| 502 | `sem_bot` | The agent did not answer the offer. Try again. |
| 503 | `desligado` | The agents are offline now. Wait for `Retry-After`. |

When speech generation fails after the charge, Lero refunds the credits at once: the `cobrado` field is `0` and the message ends with "Nada foi cobrado." ("Nothing was charged."). Transcription charges only on success: a transcription error never spends credits.