FBR Digital Invoicing Error Codes — Reference & Solutions
When you validate or submit an invoice through FBR's Digital Invoicing API, FBR returns a validation response. If something is wrong, the response carries a numeric error code (for example 0027 or 0077) and a message, at invoice level or against a specific item. Understanding these codes is the fastest way to fix an invoice. Different software surfaces FBR error codes differently, but the codes themselves come from FBR and apply to every platform.
- Find the code in the tables below (FinSmart shows the code and FBR's message on the invoice)
- Read the cause
- Fix the data on the invoice or the customer/product record
- Validate again, then submit
Error Code Categories
FBR's error codes are four-digit numbers. They fall into three practical groups:
- Header-level: seller, buyer, invoice type, invoice number and date
- Item-level: HS code, unit of measure, rate, sales tax and related tax fields, SRO references
- Connection and submission: no code or a gateway code when FBR could not be reached or did not respond in time
Codes and messages are taken from the PRAL Digital Invoicing API technical documentation (v1.12). FBR may add or change codes; always read the message that comes with the code.
📋 HEADER-LEVEL ERRORS
These errors occur when the invoice header (overall details) is incorrect.
| Error Code | FBR Message (summary) | Cause | Solution |
|---|---|---|---|
| 0001 / 0082 | Seller not registered for sales tax | The seller NTN on the invoice is not a sales tax registered person, or does not match the token. | Check the seller NTN in your business settings matches your IRIS registration. In sandbox, make sure you are using the sandbox token for that NTN. |
| 0002 | Invalid buyer registration no. or NTN | Buyer identifier is not in the right format: CNIC must be 13 digits, NTN 7 digits. | Correct the NTN or CNIC on the customer record. Remove spaces and dashes. |
| 0003 / 0011 / 0109 | Invoice type invalid or empty | Invoice type must be a valid value (Sale Invoice or Debit Note). | Use the standard sale invoice type. FinSmart sets this automatically. |
| 0005 / 0042 / 0043 / 0113 | Invoice date missing or in wrong format | Date must be in YYYY-MM-DD format and valid. | Check the invoice date. FinSmart formats the date for you. |
| 0009 / 0010 / 0012 | Buyer registration no., name or registration type missing | A required buyer field is empty. | Complete the customer record: name, NTN or CNIC, and registration type (Registered / Unregistered). |
| 0053 | Buyer registration type invalid | The registration type does not match FBR's records for that buyer. | Use FinSmart's real-time buyer registration check and save the result on the customer. |
| 0058 | Self-invoicing not allowed | Buyer and seller registration numbers are the same. | Select the correct customer. |
| 0041 / 0088 | Invoice no. missing or in wrong format | Invoice number is empty, or contains characters other than letters, digits and hyphens between characters. | FinSmart's financial-year numbering produces a valid format; avoid special characters in prefixes. |
| 0073 / 0074 | Sale origination province or destination of supply missing | Province fields are empty. | Set the business province and the buyer's province on the customer record. |
| 0106 / 0107 / 0108 | Buyer not registered / registration mismatch / invalid seller NTN | Buyer marked Registered is not a sales tax registered person, or seller details are wrong. | Re-check the buyer's registration type with FBR's service; correct the seller NTN in settings. |
🛍️ ITEM-LEVEL ERRORS
These errors occur when product/item data within the invoice is incorrect.
| Error Code | FBR Message (summary) | Cause | Solution |
|---|---|---|---|
| 0019 / 0044 | HS code missing | The item has no HS code. | Set the HS code on the item's category. FinSmart looks up HS codes from FBR reference data. |
| 0052 | HS code does not match the sale type | The HS code is valid but not allowed with the selected sale type. | Choose the correct sale type for the goods, or the correct HS code. Check the FBR rate-by-sale-type lookup. |
| 0096 / 0097 / 0099 | Unit of measure does not match the HS code | UoM must be one of the units FBR allows for that HS code (for example KG for some codes, KWH for electricity). | FinSmart lists the UoM allowed per HS code; pick from that list. |
| 0013 / 0092 / 0007 | Sale type missing or wrong | Sale type is empty, invalid, or not allowed for this seller. | Select the sale type from FBR's list. Manufacturers, distributors and retailers have different allowed types. |
| 0020 / 0046 | Rate missing | The tax rate field is empty or not valid for the sale type. | Use the rate returned by FBR's rate lookup for the sale type and invoice date (18% standard). |
| 0021 / 0098 | Value excl. ST or quantity missing | Quantity or value of sales is empty or zero. | Enter a positive quantity and value. |
| 0018 / 0023 / 0031 | Sales tax missing | The sales tax (or FED in ST mode) field is empty. | Let FinSmart calculate sales tax from value × rate, or enter it explicitly. |
| 0104 / 0105 | Calculated sales tax mismatch | Sales tax does not equal value × rate (or the per-unit tax is wrong). | Recalculate. Check rounding and that the rate matches the sale type. FinSmart computes this for you. |
| 0022 / 0024 / 0055 / 0008 | ST withheld missing or invalid | Sales tax withheld at source is empty, or is neither zero nor equal to the sales tax when required. | Set withholding to none, 1/5, 1/10 or full as appropriate for the buyer (withholding agents, FTN holders). |
| 0032 / 0070 | STWH only for GOV/FTN holders; not allowed for unregistered buyers | Withholding was applied to a buyer who is not a withholding agent, or to an unregistered buyer. | Remove withholding, or record the buyer's FTN if they are a government/withholding-agent buyer. |
| 0077 / 0078 | SRO/Schedule no. or SRO item serial no. missing | The sale type requires an SRO schedule and item serial (reduced-rate, exempt or zero-rated goods). | Select the SRO schedule and item serial from FBR's lookup on the item. |
| 0080 / 0095 / 0091 | Further tax / extra tax missing, or extra tax must be empty | A tax field required for this sale type is empty, or a field that must be empty has a value. | For unregistered buyers, further tax applies (default 4%). Extra tax applies only to specific sale types. |
| 0089 / 0090 | FED charged or fixed/notified value missing | The sale type requires FED or a fixed/notified/retail value. | Fill the FED or fixed/notified/retail value field on the item. |
| 0079 | 5% rate not allowed when value exceeds 20,000 | A reduced rate was used on an item whose value is above the allowed limit. | Apply the standard rate or split the supply as the rules require. |
| 0026 / 0027 / 0028 / 0034 / 0057 | Debit/credit note: reference, reason or date problems | A note is missing the original invoice reference or reason, or is outside 180 days of the original invoice. | Notes must reference the original FBR invoice number with a reason. FinSmart does not issue debit or credit notes today; handle them on IRIS. |
🔧 CONNECTION & SUBMISSION ISSUES
These occur when FinSmart cannot reach FBR's servers or FBR does not answer in time. They are not data errors.
| Situation | What You See | Cause | Solution |
|---|---|---|---|
| Timeout | Invoice status "timeout"; FBR gateway code such as 101504 (send timeout) | FBR's server did not respond within the time limit. The invoice may or may not have been recorded. | FinSmart locks the invoice and does not retry on its own. Check IRIS for the invoice. If it is there, record the FBR invoice number; if not, use "Force Resubmit". |
| Authentication failed | 401 / unauthorised | The FBR token for this mode is missing, wrong or expired. | Check that the sandbox or production token is saved for your business and matches the mode you logged in with. |
| Server error | 500-series response from FBR | FBR's server had an internal problem. | Wait a few minutes and try again. If it persists, check FBR notices and contact FinSmart support. |
| Network error | Cannot connect | Internet, firewall or FBR gateway outage. | Check your connection; FinSmart's server makes the FBR call, so the outage is usually at FBR. Retry after a short wait. |
| Duplicate | Blocked before sending | An invoice with identical content was already submitted. | Open the existing invoice instead of re-creating it. |
Error Patterns by Type
Header Errors
When you see header errors: The invoice's basic details (seller, buyer, invoice type, date, number) are wrong. Fix the business settings or the customer record and validate again.
Prevention: Use FinSmart's buyer registration check and "Validate FBR Invoice" before submitting.
Item Errors
When you see item errors: A product line is wrong (HS code, UoM, sale type, rate, tax fields, SRO). FBR tells you which item. Fix that item and validate again. Learn more about HS code and UoM mapping.
Prevention: Pick HS codes, UoM, sale types and SRO items from FinSmart's FBR reference data lookups instead of typing them.
Connection Issues
When you see connection issues: It is a connectivity or FBR availability problem, not your data.
Prevention: Keep your tokens current. For timeouts, always verify on IRIS before force resubmitting, so you never create a duplicate at FBR.
Quick Troubleshooting Flow
Step 2: Fix the data (customer, item or settings)
Step 3: Validate again, then submit
Step 4: If the same error persists after fixing the data, contact FinSmart support
When to Contact Support
Contact FinSmart support if you:
- Get the same error again after applying the fix
- Have a timed-out invoice and are unsure what IRIS shows
- Don't understand an error code or message
- Think an error is a FinSmart bug rather than a data problem
Support Contact: info@finsmart.pk | WhatsApp: +92 316 8222144
How FinSmart Helps With These Errors
- Validate before submit: "Validate FBR Invoice" returns FBR's codes before anything is recorded; "Submit to FBR" always validates first
- Reference data lookups: Buyer registration type, HS codes, UoM per HS code, sale types, rates by date, SRO schedules and items — all from FBR's services
- Submission safety: Invoice locking, timeout flagging with verify-on-IRIS and force resubmit, duplicate protection — no silent automatic retries
- Audit log: Every FBR request and response is logged server-side for support and audits
Official Error Code Reference
The complete list of codes and messages is in PRAL's Digital Invoicing API technical documentation, available to enrolled businesses through:
Ready to Submit?
Use FinSmart to catch these errors before submission. Our platform validates invoices against FBR and shows you exactly what to fix.
Book a free demo