# Codigos de Erro

Referencia completa de todos os codigos de erro retornados pela API Monetarie NPC.

## Formato de Resposta de Erro

Todas as respostas de erro seguem um formato padronizado:

```json
{
  "success": false,
  "error": {
    "code": "CODIGO_DO_ERRO",
    "message": "Descricao legivel do erro",
    "details": "Informacoes adicionais para resolver o problema"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

| Campo           | Tipo   | Descricao                                    |
|-----------------|--------|----------------------------------------------|
| `success`       | boolean| Sempre `false` para erros                    |
| `error.code`    | string | Codigo identificador do erro (use em logica) |
| `error.message` | string | Mensagem descritiva do erro                  |
| `error.details` | string | Detalhes adicionais ou sugestoes de correcao |
| `meta.request_id` | string | ID unico da requisicao (importante para suporte) |

::: tip Request ID
Sempre inclua o `request_id` ao entrar em contato com o suporte. Isso permite rastrear sua requisicao especifica em nossos logs.
:::

---

## Erros de Autenticacao (401)

Erros relacionados a autenticacao da API Key.

### MISSING_API_KEY

O cabecalho `X-API-Key` nao foi incluido na requisicao.

```json
{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "O cabecalho X-API-Key e obrigatorio",
    "details": "Inclua sua API Key no cabecalho X-API-Key da requisicao"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Adicione o cabecalho `X-API-Key` com sua chave de API.

### INVALID_API_KEY

A API Key fornecida e invalida ou nao existe.

```json
{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "API Key invalida ou expirada",
    "details": "Verifique se a chave esta correta e ativa no portal"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Verifique se a API Key esta correta. Gere uma nova chave no portal se necessario.

### API_KEY_REVOKED

A API Key foi revogada e nao pode mais ser utilizada.

```json
{
  "success": false,
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "Esta API Key foi revogada",
    "details": "Gere uma nova chave no portal ou entre em contato com o suporte"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Acesse o Monetarie Portal e gere uma nova API Key.

---

## Erros de Autorizacao (403)

Erros relacionados a permissoes e acesso.

### FORBIDDEN

A API Key nao possui permissao para acessar este recurso.

```json
{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Acesso negado a este recurso",
    "details": "Sua API Key nao possui permissao para esta operacao"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Verifique as permissoes da sua API Key no portal ou entre em contato com o suporte.

### IP_NOT_ALLOWED

A requisicao foi feita de um IP nao autorizado.

```json
{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "IP nao autorizado",
    "details": "O IP 203.0.113.50 nao esta na lista de IPs permitidos"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Adicione o IP de origem na lista de IPs permitidos no portal.

---

## Erros de Validacao (400/422)

Erros relacionados a dados invalidos na requisicao.

### VALIDATION_ERROR

Um ou mais campos da requisicao sao invalidos.

```json
{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Dados invalidos na requisicao",
    "details": {
      "amount_cents": ["deve ser maior que 0"],
      "due_date": ["deve ser uma data futura"],
      "payer_document": ["formato invalido"]
    }
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Corrija os campos indicados no objeto `details`.

### INVALID_DOCUMENT

O documento (CPF/CNPJ) fornecido e invalido.

```json
{
  "success": false,
  "error": {
    "code": "INVALID_DOCUMENT",
    "message": "Documento invalido",
    "details": "O CPF/CNPJ '12345678900' nao possui digitos verificadores validos"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Verifique se o CPF ou CNPJ esta correto, incluindo os digitos verificadores.

### INVALID_DUE_DATE

A data de vencimento e invalida ou esta no passado.

```json
{
  "success": false,
  "error": {
    "code": "INVALID_DUE_DATE",
    "message": "Data de vencimento invalida",
    "details": "A data de vencimento deve ser igual ou posterior a data atual"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Use uma data de vencimento no futuro no formato `YYYY-MM-DD`.

### AMOUNT_TOO_LOW

O valor do boleto e menor que o minimo permitido.

```json
{
  "success": false,
  "error": {
    "code": "AMOUNT_TOO_LOW",
    "message": "Valor muito baixo",
    "details": "O valor minimo para um boleto e R$ 1,00 (100 centavos)"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** O valor minimo e 100 centavos (R$ 1,00).

---

## Erros de Recurso (404/409)

Erros relacionados a recursos nao encontrados ou conflitos.

### NOT_FOUND

O recurso solicitado nao foi encontrado.

```json
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Recurso nao encontrado",
    "details": "O recurso solicitado nao existe ou foi removido"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

### BOLETO_NOT_FOUND

O boleto especificado nao foi encontrado.

```json
{
  "success": false,
  "error": {
    "code": "BOLETO_NOT_FOUND",
    "message": "Boleto nao encontrado",
    "details": "Nenhum boleto encontrado com nosso_numero '12345678901'"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Verifique se o `nosso_numero` esta correto.

### DUPLICATE_BOLETO

Ja existe um boleto com o mesmo `nosso_numero`.

```json
{
  "success": false,
  "error": {
    "code": "DUPLICATE_BOLETO",
    "message": "Boleto duplicado",
    "details": "Ja existe um boleto com nosso_numero '12345678901'"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Use um `nosso_numero` unico para cada boleto.

### INVALID_STATUS_TRANSITION

A transicao de status solicitada nao e permitida.

```json
{
  "success": false,
  "error": {
    "code": "INVALID_STATUS_TRANSITION",
    "message": "Transicao de status invalida",
    "details": "Nao e possivel alterar o status de 'paid' para 'cancelled'"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Verifique o diagrama de transicoes de status abaixo.

### Diagrama de Transicoes de Status

O ciclo de vida de um boleto segue regras estritas de transicao:

```
                    +-----------+
                    |   draft   |
                    +-----+-----+
                          |
                          | registrar
                          v
                    +-----------+
            +------>| registered|<------+
            |       +-----+-----+       |
            |             |             |
            | cancelar    | pagar       | cancelar
            |             v             |
            |       +-----------+       |
            +-------+   paid    +-------+
                    +-----+-----+
                          |
                          | liquidar
                          v
                    +-----------+
                    |  settled  |
                    +-----------+

                    +-----------+
                    | cancelled | (estado final)
                    +-----------+
```

**Transicoes permitidas:**

| Status Atual  | Transicoes Possiveis           |
|---------------|-------------------------------|
| `draft`       | `registered`                  |
| `registered`  | `paid`, `cancelled`           |
| `paid`        | `settled`                     |
| `settled`     | (nenhuma - estado final)      |
| `cancelled`   | (nenhuma - estado final)      |

---

## Erros de Rate Limit (429)

Erros relacionados a limites de requisicoes.

### RATE_LIMITED

O limite de requisicoes foi excedido.

```json
{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Limite de requisicoes excedido",
    "details": "Aguarde 45 segundos antes de fazer novas requisicoes"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Headers retornados:**

| Header                 | Valor    | Descricao                               |
|------------------------|----------|----------------------------------------|
| `X-RateLimit-Limit`    | `100`    | Limite total de requisicoes             |
| `X-RateLimit-Remaining`| `0`      | Requisicoes restantes                   |
| `X-RateLimit-Reset`    | `1706968800` | Timestamp Unix quando o limite reseta |
| `Retry-After`          | `45`     | Segundos para aguardar                  |

**Como resolver:** Aguarde o tempo indicado no header `Retry-After` antes de tentar novamente.

Consulte a pagina de [Rate Limits](/reference/rate-limits) para mais detalhes.

---

## Erros de Servidor (500/503)

Erros internos ou de indisponibilidade.

### INTERNAL_ERROR

Erro interno do servidor.

```json
{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Erro interno do servidor",
    "details": "Ocorreu um erro inesperado. Nossa equipe foi notificada."
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Tente novamente em alguns minutos. Se o problema persistir, entre em contato com o suporte incluindo o `request_id`.

### PCR_UNAVAILABLE

O servico PCR da Nuclea esta temporariamente indisponivel.

```json
{
  "success": false,
  "error": {
    "code": "PCR_UNAVAILABLE",
    "message": "Servico PCR indisponivel",
    "details": "O servico de registro de boletos da Nuclea esta temporariamente indisponivel"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** O servico PCR da Nuclea pode estar em manutencao. Tente novamente em alguns minutos.

### FTP_UNAVAILABLE

O servico FTP da Nuclea esta temporariamente indisponivel.

```json
{
  "success": false,
  "error": {
    "code": "FTP_UNAVAILABLE",
    "message": "Servico FTP indisponivel",
    "details": "O servico de arquivos da Nuclea esta temporariamente indisponivel"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}
```

**Como resolver:** Os arquivos de liquidacao sao processados automaticamente quando o servico normalizar.

---

## Tratamento de Erros

### Exemplo em JavaScript

```javascript
async function createBoleto(boletoData) {
  try {
    const response = await fetch(
      "https://api.monetarie_npc.com.br/api/v1/central/boletos",
      {
        method: "POST",
        headers: {
          "X-API-Key": process.env.MONETARIE_NPC_API_KEY,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ boleto: boletoData }),
      }
    );

    const data = await response.json();

    if (!response.ok) {
      // Tratar erros especificos
      switch (data.error.code) {
        case "VALIDATION_ERROR":
          console.error("Dados invalidos:", data.error.details);
          // Mostrar erros de validacao para o usuario
          break;

        case "DUPLICATE_BOLETO":
          console.error("Boleto ja existe:", data.error.message);
          // Buscar boleto existente
          break;

        case "RATE_LIMITED":
          const retryAfter = response.headers.get("Retry-After");
          console.log(`Aguardando ${retryAfter} segundos...`);
          // Implementar retry com backoff
          break;

        case "PCR_UNAVAILABLE":
        case "INTERNAL_ERROR":
          console.error("Erro do servidor:", data.error.message);
          // Agendar retry
          break;

        default:
          console.error("Erro desconhecido:", data.error);
      }

      // Logar request_id para suporte
      console.log("Request ID:", data.meta.request_id);
      return null;
    }

    return data.data;
  } catch (error) {
    console.error("Erro de rede:", error);
    throw error;
  }
}
```

### Exemplo em Python

```python
import requests
import time
import os

def create_boleto(boleto_data):
    url = "https://api.monetarie_npc.com.br/api/v1/central/boletos"
    headers = {
        "X-API-Key": os.environ["MONETARIE_NPC_API_KEY"],
        "Content-Type": "application/json"
    }

    try:
        response = requests.post(
            url,
            headers=headers,
            json={"boleto": boleto_data}
        )
        data = response.json()

        if not response.ok:
            error = data.get("error", {})
            error_code = error.get("code")
            request_id = data.get("meta", {}).get("request_id")

            # Tratar erros especificos
            if error_code == "VALIDATION_ERROR":
                print(f"Dados invalidos: {error.get('details')}")
                # Mostrar erros de validacao para o usuario

            elif error_code == "DUPLICATE_BOLETO":
                print(f"Boleto ja existe: {error.get('message')}")
                # Buscar boleto existente

            elif error_code == "RATE_LIMITED":
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Rate limited. Aguardando {retry_after} segundos...")
                time.sleep(retry_after)
                # Tentar novamente
                return create_boleto(boleto_data)

            elif error_code in ["PCR_UNAVAILABLE", "INTERNAL_ERROR"]:
                print(f"Erro do servidor: {error.get('message')}")
                # Agendar retry

            # Logar request_id para suporte
            print(f"Request ID: {request_id}")
            return None

        return data.get("data")

    except requests.exceptions.RequestException as e:
        print(f"Erro de rede: {e}")
        raise
```

---

## Contato com Suporte

Ao entrar em contato com o suporte, sempre inclua:

1. **Request ID** - O `request_id` retornado na resposta de erro
2. **Timestamp** - Data e hora aproximada do erro
3. **Endpoint** - URL e metodo HTTP utilizado
4. **Payload** - Corpo da requisicao (remova dados sensiveis)
5. **Resposta** - A resposta completa de erro recebida

::: info Canais de Suporte
- **Email:** suporte@fluxiq.com.br
- **Portal:** [npcadmin-dev.fluxiq.com.br/suporte](https://npcadmin-dev.fluxiq.com.br/suporte)
- **SLA:** Respostas em ate 4 horas uteis para ambiente de producao
:::

## Proximos Passos

- [Rate Limits](/reference/rate-limits) - Limites de requisicoes por endpoint
- [Autenticacao](/authentication) - Configurar API Key corretamente
- [Ambientes](/environments) - Usar sandbox para testes