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

# Erros e Códigos

> Tratamento de erros e códigos de status da API

## Erros e Códigos

A API utiliza códigos de status HTTP padrão e retorna mensagens de erro estruturadas para facilitar o diagnóstico e tratamento de problemas.

## Formato de Erro

```json theme={null}
{
  "status": "error",
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "O campo 'name' é obrigatório.",
    "details": [
      {
        "field": "name",
        "message": "Este campo não pode ser vazio."
      }
    ]
  },
  "meta": {
    "request_id": "req-uuid",
    "timestamp": "2026-01-15T10:30:00Z"
  }
}
```

## Códigos de Status HTTP

| Código  | Significado           | Uso                                           |
| ------- | --------------------- | --------------------------------------------- |
| **200** | OK                    | Requisição bem-sucedida                       |
| **201** | Created               | Recurso criado com sucesso                    |
| **204** | No Content            | Operação bem-sucedida sem conteúdo de retorno |
| **400** | Bad Request           | Dados inválidos ou malformados                |
| **401** | Unauthorized          | Token ausente ou inválido                     |
| **403** | Forbidden             | Sem permissão para acessar o recurso          |
| **404** | Not Found             | Recurso não encontrado                        |
| **409** | Conflict              | Conflito (ex: registro duplicado)             |
| **422** | Unprocessable Entity  | Erro de validação nos dados enviados          |
| **429** | Too Many Requests     | Limite de requisições excedido                |
| **500** | Internal Server Error | Erro interno do servidor                      |

## Códigos de Erro Internos

| Código                 | Descrição                            |
| ---------------------- | ------------------------------------ |
| `VALIDATION_ERROR`     | Erro de validação nos dados enviados |
| `AUTHENTICATION_ERROR` | Falha na autenticação                |
| `AUTHORIZATION_ERROR`  | Sem permissão para a operação        |
| `RESOURCE_NOT_FOUND`   | Recurso solicitado não existe        |
| `DUPLICATE_RESOURCE`   | Tentativa de criar recurso duplicado |
| `RATE_LIMIT_EXCEEDED`  | Limite de requisições excedido       |
| `INTERNAL_ERROR`       | Erro interno não especificado        |