Error Codes

Complete reference of all error codes returned by the FluxiQ NPC API.

Error Response Format

All error responses follow a standardized format:

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": "Additional information to resolve the problem"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Field	Type	Description
success	boolean	Always false for errors
error.code	string	Error identifier code (use in logic)
error.message	string	Descriptive error message
error.details	string	Additional details or correction suggestions
meta.request_id	string	Unique request ID (important for support)

Request ID

Always include the request_id when contacting support. This allows us to trace your specific request in our logs.

---

Authentication Errors (401)

Errors related to API Key authentication.

MISSING_API_KEY

The X-API-Key header was not included in the request.

{
  "success": false,
  "error": {
    "code": "MISSING_API_KEY",
    "message": "The X-API-Key header is required",
    "details": "Include your API Key in the X-API-Key header of the request"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Add the X-API-Key header with your API key.

INVALID_API_KEY

The provided API Key is invalid or does not exist.

{
  "success": false,
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or expired API Key",
    "details": "Verify that the key is correct and active in the portal"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Verify that the API Key is correct. Generate a new key in the portal if necessary.

API_KEY_REVOKED

The API Key has been revoked and can no longer be used.

{
  "success": false,
  "error": {
    "code": "API_KEY_REVOKED",
    "message": "This API Key has been revoked",
    "details": "Generate a new key in the portal or contact support"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Access the FluxiQ Portal and generate a new API Key.

---

Authorization Errors (403)

Errors related to permissions and access.

FORBIDDEN

The API Key does not have permission to access this resource.

{
  "success": false,
  "error": {
    "code": "FORBIDDEN",
    "message": "Access denied to this resource",
    "details": "Your API Key does not have permission for this operation"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Check your API Key permissions in the portal or contact support.

IP_NOT_ALLOWED

The request was made from an unauthorized IP.

{
  "success": false,
  "error": {
    "code": "IP_NOT_ALLOWED",
    "message": "IP not authorized",
    "details": "IP 203.0.113.50 is not in the allowed IP list"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Add the source IP to the allowed IP list in the portal.

---

Validation Errors (400/422)

Errors related to invalid data in the request.

VALIDATION_ERROR

One or more request fields are invalid.

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid data in request",
    "details": {
      "amount_cents": ["must be greater than 0"],
      "due_date": ["must be a future date"],
      "payer_document": ["invalid format"]
    }
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Correct the fields indicated in the details object.

INVALID_DOCUMENT

The document (CPF/CNPJ) provided is invalid.

{
  "success": false,
  "error": {
    "code": "INVALID_DOCUMENT",
    "message": "Invalid document",
    "details": "The CPF/CNPJ '12345678900' does not have valid check digits"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Verify that the CPF or CNPJ is correct, including check digits.

INVALID_DUE_DATE

The due date is invalid or in the past.

{
  "success": false,
  "error": {
    "code": "INVALID_DUE_DATE",
    "message": "Invalid due date",
    "details": "The due date must be equal to or later than the current date"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Use a future due date in YYYY-MM-DD format.

AMOUNT_TOO_LOW

The boleto value is less than the allowed minimum.

{
  "success": false,
  "error": {
    "code": "AMOUNT_TOO_LOW",
    "message": "Value too low",
    "details": "The minimum value for a boleto is R$ 1.00 (100 cents)"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: The minimum value is 100 cents (R$ 1.00).

---

Resource Errors (404/409)

Errors related to resources not found or conflicts.

NOT_FOUND

The requested resource was not found.

{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Resource not found",
    "details": "The requested resource does not exist or has been removed"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

BOLETO_NOT_FOUND

The specified boleto was not found.

{
  "success": false,
  "error": {
    "code": "BOLETO_NOT_FOUND",
    "message": "Boleto not found",
    "details": "No boleto found with nosso_numero '12345678901'"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Verify that the nosso_numero is correct.

DUPLICATE_BOLETO

A boleto with the same nosso_numero already exists.

{
  "success": false,
  "error": {
    "code": "DUPLICATE_BOLETO",
    "message": "Duplicate boleto",
    "details": "A boleto with nosso_numero '12345678901' already exists"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Use a unique nosso_numero for each boleto.

INVALID_STATUS_TRANSITION

The requested status transition is not allowed.

{
  "success": false,
  "error": {
    "code": "INVALID_STATUS_TRANSITION",
    "message": "Invalid status transition",
    "details": "Cannot change status from 'paid' to 'cancelled'"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Check the status transition diagram below.

Status Transition Diagram

The boleto lifecycle follows strict transition rules:

                    +-----------+
                    |   draft   |
                    +-----+-----+
                          |
                          | register
                          v
                    +-----------+
            +------>| registered|<------+
            |       +-----+-----+       |
            |             |             |
            | cancel      | pay         | cancel
            |             v             |
            |       +-----------+       |
            +-------+   paid    +-------+
                    +-----+-----+
                          |
                          | settle
                          v
                    +-----------+
                    |  settled  |
                    +-----------+

                    +-----------+
                    | cancelled | (final state)
                    +-----------+

Allowed transitions:

Current Status	Possible Transitions
draft	registered
registered	paid, cancelled
paid	settled
settled	(none - final state)
cancelled	(none - final state)

---

Rate Limit Errors (429)

Errors related to request limits.

RATE_LIMITED

The request limit has been exceeded.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "Request limit exceeded",
    "details": "Wait 45 seconds before making new requests"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

Headers returned:

Header	Value	Description
X-RateLimit-Limit	100	Total request limit
X-RateLimit-Remaining	0	Remaining requests
X-RateLimit-Reset	1706968800	Unix timestamp when limit resets
Retry-After	45	Seconds to wait

How to resolve: Wait the time indicated in the Retry-After header before trying again.

See the Rate Limits page for more details.

---

Server Errors (500/503)

Internal or unavailability errors.

INTERNAL_ERROR

Internal server error.

{
  "success": false,
  "error": {
    "code": "INTERNAL_ERROR",
    "message": "Internal server error",
    "details": "An unexpected error occurred. Our team has been notified."
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Try again in a few minutes. If the problem persists, contact support including the request_id.

PCR_UNAVAILABLE

Nuclea's PCR service is temporarily unavailable.

{
  "success": false,
  "error": {
    "code": "PCR_UNAVAILABLE",
    "message": "PCR service unavailable",
    "details": "Nuclea's boleto registration service is temporarily unavailable"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Nuclea's PCR service may be under maintenance. Try again in a few minutes.

FTP_UNAVAILABLE

Nuclea's FTP service is temporarily unavailable.

{
  "success": false,
  "error": {
    "code": "FTP_UNAVAILABLE",
    "message": "FTP service unavailable",
    "details": "Nuclea's file service is temporarily unavailable"
  },
  "meta": {
    "request_id": "req_abc123def456"
  }
}

How to resolve: Settlement files are automatically processed when the service normalizes.

---

Error Handling

JavaScript Example

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) {
      // Handle specific errors
      switch (data.error.code) {
        case "VALIDATION_ERROR":
          console.error("Invalid data:", data.error.details);
          // Show validation errors to user
          break;

        case "DUPLICATE_BOLETO":
          console.error("Boleto already exists:", data.error.message);
          // Fetch existing boleto
          break;

        case "RATE_LIMITED":
          const retryAfter = response.headers.get("Retry-After");
          console.log(`Waiting ${retryAfter} seconds...`);
          // Implement retry with backoff
          break;

        case "PCR_UNAVAILABLE":
        case "INTERNAL_ERROR":
          console.error("Server error:", data.error.message);
          // Schedule retry
          break;

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

      // Log request_id for support
      console.log("Request ID:", data.meta.request_id);
      return null;
    }

    return data.data;
  } catch (error) {
    console.error("Network error:", error);
    throw error;
  }
}

Python Example

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")

            # Handle specific errors
            if error_code == "VALIDATION_ERROR":
                print(f"Invalid data: {error.get('details')}")
                # Show validation errors to user

            elif error_code == "DUPLICATE_BOLETO":
                print(f"Boleto already exists: {error.get('message')}")
                # Fetch existing boleto

            elif error_code == "RATE_LIMITED":
                retry_after = int(response.headers.get("Retry-After", 60))
                print(f"Rate limited. Waiting {retry_after} seconds...")
                time.sleep(retry_after)
                # Try again
                return create_boleto(boleto_data)

            elif error_code in ["PCR_UNAVAILABLE", "INTERNAL_ERROR"]:
                print(f"Server error: {error.get('message')}")
                # Schedule retry

            # Log request_id for support
            print(f"Request ID: {request_id}")
            return None

        return data.get("data")

    except requests.exceptions.RequestException as e:
        print(f"Network error: {e}")
        raise

---

Contacting Support

When contacting support, always include:

1. Request ID - The request_id returned in the error response
2. Timestamp - Approximate date and time of the error
3. Endpoint - URL and HTTP method used
4. Payload - Request body (remove sensitive data)
5. Response - Complete error response received

Support Channels

• Email: suporte@fluxiq.com.br
• Portal: npcadmin-dev.fluxiq.com.br/suporte
• SLA: Responses within 4 business hours for production environment

Next Steps

• Rate Limits - Request limits per endpoint
• Authentication - Configure API Key correctly
• Environments - Use sandbox for testing