Troubleshooting
Guide for resolving the most common errors when issuing NF-e through the NF-e SP connector.
Rejection 225 - XML Schema Failure
Message: Rejeicao: Falha no Schema XML do lote de NFe
This is the most common rejection. It means the XML generated from your JSON does not pass SEFAZ's XSD validation. Below are the most frequent causes.
Leading zeros in numeric fields
Fields like serie and n_nf do not accept leading zeros.
# WRONG
"serie": "003" # SEFAZ rejects leading zeros
"n_nf": "074110" # Same issue
# CORRECT
"serie": "3"
"n_nf": "74110"
Valid patterns:
| Field | Pattern | Allowed values |
|---|---|---|
serie | 0 or 1-999 | "0", "1", "999" |
n_nf | 1-999999999 | "1", "74110", "999999999" |
imposto_devol in the wrong position
For return invoices, imposto_devol must be a sibling of imposto inside det, not a child of imposto or ipi.
# WRONG - inside imposto
"imposto": {
"icms": { ... },
"imposto_devol": { ... }
}
# WRONG - inside ipi
"imposto": {
"ipi": {
"ipi_devol": { ... }
}
}
# CORRECT - sibling of imposto inside det
"det": [{
"prod": { ... },
"imposto": { ... },
"imposto_devol": {
"p_devol": "100.00",
"ipi": { "v_ipi_devol": "16.90" }
}
}]
Missing timezone in datetime fields
The dh_emi field requires a timezone offset.
# WRONG
"dh_emi": "2026-03-26T10:00:00"
# CORRECT
"dh_emi": "2026-03-26T10:00:00-03:00"
Wrong decimal format
Decimal fields have strict formatting rules. The number of decimal places matters.
# WRONG
"v_prod": "100.5" # Needs exactly 2 decimals
"p_icms": "18" # Needs 2-4 decimals
# CORRECT
"v_prod": "100.50"
"p_icms": "18.0000"
Decimal rules by field type:
| Fields | Integer digits | Decimal places | Example |
|---|---|---|---|
Values (v_bc, v_prod, v_icms, etc.) | up to 13 | exactly 2 | "519.92" |
Rates (p_icms, p_ipi, p_pis, etc.) | up to 3 | 2 to 4 | "12.0000" |
Quantities (q_com, q_trib) | up to 11 | 1 to 4 | "1.0000" |
Unit values (v_un_com, v_un_trib) | up to 11 | 1 to 10 | "519.9200" |
Multiple tax variants in the same item
Each tax group (ICMS, PIS, COFINS, IPI) accepts only one variant per item.
# WRONG - two ICMS variants
"icms": {
"icms00": { ... },
"icms20": { ... }
}
# WRONG - two IPI variants
"ipi": {
"ipi_trib": { ... },
"ipint": { ... }
}
# CORRECT - only one variant per tax
"icms": {
"icms00": { ... }
}
Invalid GTIN/EAN
The c_ean and c_ean_trib fields accept only specific formats.
# WRONG
"c_ean": "123456789" # 9 digits - not valid
# CORRECT
"c_ean": "SEM GTIN" # No barcode
"c_ean": "12345678" # 8 digits (EAN-8)
"c_ean": "123456789012" # 12 digits (UPC)
"c_ean": "1234567890123" # 13 digits (EAN-13)
"c_ean": "12345678901234" # 14 digits (EAN-14)
Invalid CFOP
CFOP must be 4 digits and start with 1, 2, 3, 5, 6, or 7.
# WRONG
"cfop": "0102" # Cannot start with 0
"cfop": "4102" # Cannot start with 4
# CORRECT
"cfop": "5102" # Internal sale
"cfop": "6202" # Interstate return
Text fields with leading/trailing spaces
Text fields (like x_nome, x_prod, nat_op) cannot start or end with spaces.
# WRONG
"x_nome": " COMPANY NAME "
"x_prod": "PRODUCT "
# CORRECT
"x_nome": "COMPANY NAME"
"x_prod": "PRODUCT"
Rejection 502 - Access Key Mismatch
Message: Rejeicao: Erro na Chave de Acesso - campo ID
The manually provided access key doesn't match the concatenation of the NF-e fields.
Solution: Don't pass the id field manually. Let the connector generate the access key automatically:
# WRONG - manual access key that may be inconsistent
"inf_nfe": {
"id": "35260312345678000199550030000741101781746768",
"ide": {
"serie": "1", # Doesn't match serie "003" in the key above
...
}
}
# CORRECT - let the connector generate it
"inf_nfe": {
# No "id" field
"ide": {
"serie": "3",
...
}
}
Rejection 539 / 540 - Duplicate NF-e
Message: Rejeicao: Duplicidade de NF-e
An NF-e with the same access key (same serie + n_nf + emit CNPJ) was already authorized.
Solution: Increment the n_nf (invoice number) or use a different c_nf (random code).
Rejection 215 - Signature Error
Message: Rejeicao: Falha no Schema XML - elemento assinatura
Possible causes:
- Expired certificate
- Certificate without private key
- Certificate not issued by ICP-Brasil
Solution: Check your certificate configuration:
# Verify certificate validity
import base64
from cryptography.hazmat.primitives.serialization import pkcs12
pfx_b64 = "..." # Your certificate in Base64
pfx_bytes = base64.b64decode(pfx_b64)
private_key, certificate, _ = pkcs12.load_key_and_certificates(pfx_bytes, b"your_password")
print(f"Valid from: {certificate.not_valid_before_utc}")
print(f"Valid until: {certificate.not_valid_after_utc}")
print(f"Has private key: {private_key is not None}")
Authentication Errors
mTLS / Certificate not accepted
Cause: The SEFAZ server could not validate the digital certificate during the TLS handshake.
Solutions:
- Confirm the certificate password is correct
- Check if the certificate is not expired
- Make sure the certificate contains the full certification chain
- Verify the certificate is type A1 (PFX/P12 format)
General Tips
1. Use homologacao first
Set environment: "homologacao" in the connector configuration to test before production.
2. Start with minimal fields
Begin with only the required fields and add optional ones as needed. This makes it easier to identify which field is causing the rejection.
3. Check the connector's validation warnings
The connector performs XSD validation before sending to SEFAZ. If there are validation issues, they will appear in the response under _validation_warnings:
result = run_connection_action("nfe-sp", "nfe_autorizacao", params)
if "_validation_warnings" in result:
print("Validation warnings:", result["_validation_warnings"])
4. Parse the SEFAZ response
The SEFAZ response includes c_stat (status code) and x_motivo (reason):
result = run_connection_action("nfe-sp", "nfe_autorizacao", params)
# For synchronous requests (ind_sinc="1")
ret = result.get("ret_envi_nfe", {})
print(f"Status: {ret.get('c_stat')}")
print(f"Reason: {ret.get('x_motivo')}")
# Check individual NF-e protocol
prot = ret.get("prot_nfe", {}).get("inf_prot", {})
print(f"NF-e Status: {prot.get('c_stat')}")
print(f"NF-e Reason: {prot.get('x_motivo')}")