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

# Erros e códigos HTTP

> Formato de erro da v0x API e status comuns

A v0x API retorna erros em JSON simples:

```json theme={"theme":{"light":"github-light","dark":"one-dark-pro"}}
{
  "error": "unauthorized"
}
```

O campo `error` é o código estável para lógica do integrador.

## Status HTTP frequentes

| Status | Situação típica                 |
| ------ | ------------------------------- |
| `401`  | Sessão ou API key inválida      |
| `403`  | Quota de storage excedida       |
| `404`  | Arquivo ou chave não encontrada |
| `413`  | Arquivo acima do limite         |
| `429`  | Rate limit excedido             |
| `500`  | Erro interno                    |

## Códigos de domínio

| Código                   | HTTP | Significado                       |
| ------------------------ | ---- | --------------------------------- |
| `unauthorized`           | 401  | Cookie ou Bearer ausente/inválido |
| `invalid_multipart`      | 400  | Body multipart malformado         |
| `file_required`          | 400  | Campo `file` ausente              |
| `storage_limit_exceeded` | 403  | Quota de 2 GB esgotada            |
| `file_too_large`         | 413  | Arquivo acima de 100 MB           |
| `not_found`              | 404  | Arquivo ou recurso inexistente    |
| `rate_limit_exceeded`    | 429  | Muitas requisições                |
| `upload_failed`          | 500  | Falha no storage                  |
| `list_failed`            | 500  | Erro ao listar arquivos           |
| `get_failed`             | 500  | Erro ao buscar arquivo            |
| `delete_failed`          | 500  | Erro ao excluir                   |

## Boas práticas

* Trate `error` como enum estável, não a mensagem HTTP
* Retente `429` e `5xx` com backoff
* Não exponha erros internos ao usuário final — logue no servidor

Veja também: [Primeira integração](/pages/guides/primeira-integracao) · [Boas práticas](/pages/guides/boas-praticas)