Codigos de Erro

Referencia completa de todos os codigos de erro retornados pela API FluxiQ 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)

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 FluxiQ 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 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.pixconnect.com.br/api/v1/central/boletos",
      {
        method: "POST",
        headers: {
          "X-API-Key": process.env.PIXCONNECT_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.pixconnect.com.br/api/v1/central/boletos"
    headers = {
        "X-API-Key": os.environ["PIXCONNECT_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:

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

Canais de Suporte

Email: suporte@fluxiq.com.br
Portal: npcadmin-dev.fluxiq.com.br/suporte
SLA: Respostas em ate 4 horas uteis para ambiente de producao

Proximos Passos

Rate Limits - Limites de requisicoes por endpoint
Autenticacao - Configurar API Key corretamente
Ambientes - Usar sandbox para testes

Codigos de Erro ​

Formato de Resposta de Erro ​

Erros de Autenticacao (401) ​

MISSING_API_KEY ​

INVALID_API_KEY ​

API_KEY_REVOKED ​

Erros de Autorizacao (403) ​

FORBIDDEN ​

IP_NOT_ALLOWED ​

Erros de Validacao (400/422) ​

VALIDATION_ERROR ​

INVALID_DOCUMENT ​

INVALID_DUE_DATE ​

AMOUNT_TOO_LOW ​

Erros de Recurso (404/409) ​

NOT_FOUND ​

BOLETO_NOT_FOUND ​

DUPLICATE_BOLETO ​

INVALID_STATUS_TRANSITION ​

Diagrama de Transicoes de Status ​

Erros de Rate Limit (429) ​

RATE_LIMITED ​

Erros de Servidor (500/503) ​

INTERNAL_ERROR ​

PCR_UNAVAILABLE ​

FTP_UNAVAILABLE ​

Tratamento de Erros ​

Exemplo em JavaScript ​

Exemplo em Python ​

Contato com Suporte ​

Proximos Passos ​

Codigos de Erro

Formato de Resposta de Erro

Erros de Autenticacao (401)

MISSING_API_KEY

INVALID_API_KEY

API_KEY_REVOKED

Erros de Autorizacao (403)

FORBIDDEN

IP_NOT_ALLOWED

Erros de Validacao (400/422)

VALIDATION_ERROR

INVALID_DOCUMENT

INVALID_DUE_DATE

AMOUNT_TOO_LOW

Erros de Recurso (404/409)

NOT_FOUND

BOLETO_NOT_FOUND

DUPLICATE_BOLETO

INVALID_STATUS_TRANSITION

Diagrama de Transicoes de Status

Erros de Rate Limit (429)

RATE_LIMITED

Erros de Servidor (500/503)

INTERNAL_ERROR

PCR_UNAVAILABLE

FTP_UNAVAILABLE

Tratamento de Erros

Exemplo em JavaScript

Exemplo em Python

Contato com Suporte

Proximos Passos