Last reviewed: 7 October 2026. Based on PRAL's Technical Documentation for DI API v1.12. General information, not tax advice.
When your software posts an invoice to FBR Digital Invoicing and something is wrong, FBR sends back an error code and a short message such as "Provide proper HS Code with invoice no. null". The messages are terse, and the code list in the official PDF is hard to read. This guide explains the errors small businesses hit most often, in plain English, with the fix for each.
How to read an FBR DI error
There are two layers to check.
1. The HTTP status. If the request itself fails with HTTP 401 (Unauthorized), FBR never looked at your invoice. The usual causes are:
- your server's IP address is not yet whitelisted (PRAL says it decides within two working hours of submission);
- you are using a sandbox token against the production address, or the reverse;
- the token was copied with a stray space or line break.
2. The response body. Business errors come back with HTTP 200 and a status code inside the response. "00" means valid, "01" means invalid. An error can sit at invoice level (for example, a buyer problem) or at item level (one line's HS code or rate). An invoice only succeeded if it has an FBR invoice number and every item says valid. If even one item is invalid, fix it and post again.
Map errors by the message text as well as the number. The code table in PRAL's technical documentation is badly aligned in places (especially codes 0011 to 0041), and some blogs give meanings that contradict it, such as "0001 means invalid bearer token". The official 0001 is about the seller's registration.
Token and registration errors
| Code | FBR message (short) | What it means | How to fix it |
|---|---|---|---|
| 0401 | Seller NTN/CNIC does not have a valid or authorized access token | The token you sent doesn't belong to the seller NTN on the invoice, or the NTN isn't 7 digits / CNIC 13 digits | Use the token issued in IRIS for this exact NTN, and check the seller NTN field |
| 0402 | Buyer NTN/CNIC does not have a valid or authorized access token | Same check, for the buyer side | Check the buyer's NTN/CNIC format and whether you need to send it at all |
| 0001 | Seller not registered for sales tax | FBR doesn't see the seller as sales-tax-registered | Check your registration and ATL status; talk to your tax advisor if it was suspended |
| 0002 | Invalid buyer registration no or NTN | Wrong format | Buyer CNIC must be 13 digits; NTN 7 or 9 digits, no dashes |
Token errors are the first thing people hit after go-live, often because the sandbox token is still in the settings. Remember that sandbox and production tokens are different.
Buyer errors
| Message | What it means | How to fix it |
|---|---|---|
| Provide Buyer Registration Type | The field is empty | Send "Registered" or "Unregistered" |
| Provided buyer registration type is invalid | The buyer isn't what you said | Check the buyer's status (FBR's API can look it up) and correct it |
| Provide Buyer Name | Buyer name missing | Add the buyer's legal name |
| Self-invoicing not allowed | Buyer and seller NTN are the same | You can't invoice yourself; check the buyer NTN |
| Provide Destination of Supply / Sale Origination Province | Province missing | Use the exact province names from FBR's province list |
Getting the registration type right matters beyond the error: further tax usually applies to unregistered buyers, and government or withholding-agent buyers change how sales tax withheld is filled in.
Item errors: HS code, unit, rate and sale type
These cause most rejections during sandbox testing.
| Code | FBR message (short) | What it means | How to fix it |
|---|---|---|---|
| 0052 | Provide proper / valid HS Code against sale type | HS code missing, wrongly formatted, or not allowed for this sale type | Use an 8-digit code in the format 0101.2100 that fits the sale type |
| 0099 / 0104 | UOM is not valid; UOM must be according to given HS Code | The unit doesn't match what FBR allows for that HS code | Pick the unit FBR lists for that code (e.g. KG, Numbers/pieces/units) |
| 0046 | Provide rate | Rate empty or not valid for the sale type | Send the rate text FBR expects for that sale type and date, e.g. "18%" |
| 0013 | Provide valid Sale type | Sale type text doesn't match FBR's list | Copy the sale type exactly, e.g. "Goods at standard rate (default)" |
| 0077 / 0078 | Provide SRO/Schedule No. / Item Sr. No. | A reduced, exempt or zero rate needs its SRO reference | Add the SRO or schedule and the item serial number |
| 0083 | Rate 5% not allowed (value over 20,000) | A 5% reduced rate is used on a line above Rs 20,000 | Check whether the reduced rate really applies |
Our guide to HS codes for FBR invoices explains how to find the right code and unit.
Calculation errors
| Message | What it means | How to fix it |
|---|---|---|
| The calculated percentage sales tax does not match | Sales tax isn't rate x value excluding tax | Recalculate per line and round to 2 decimals |
| The calculated sales tax for the quantity is incorrect | Tax on a per-unit rate doesn't match the quantity | Check quantity and per-unit rate |
| ST withheld at source should either be zero or same as sales tax | A partial withholding amount was sent | Send 0, or the full sales tax amount |
| Calculated tax not matched in 3rd schedule | Third Schedule goods are taxed on retail price | Fill the retail price field and compute tax on it |
| Provided decimal value is not valid at field | A number is malformed | Send plain numbers, no commas or currency symbols |
Rounding is the silent killer. Compute tax per line, round half-up to 2 decimals, and make the invoice total the sum of the rounded lines.
Date, debit note and credit note errors
| Message | How to fix it |
|---|---|
| Please provide date in valid format | Use YYYY-MM-DD, e.g. 2026-10-07 |
| Invoice Reference No. is required | Debit or credit notes must quote the original FBR invoice number |
| Reference Invoice does not exist | The original FBR number is wrong, or it belongs to another seller |
| Debit/Credit note can only be added within 180 days | The original invoice is too old for a note |
| Note date must be greater or equal to original invoice date | Date the note on or after the original |
When the error isn't your fault
Sometimes posting fails because of FBR's side: timeouts, maintenance or a gateway error (HTTP 500). Be careful here. The DI system has no automatic retry or duplicate protection, so if a request times out, FBR may already have issued a number. Before you post again, search for the invoice by date in the IRIS invoice dashboard. If you do create a duplicate, cancel it within the 72-hour window.
For persistent problems, raise a ticket with PRAL at dicrm.pral.com.pk with the full request and response.
What we could not confirm
- The official PDF's code-to-message alignment is imperfect, so some codes above (especially in the 0011 to 0041 range) may map differently in the live system. Trust the message text.
- PRAL has not published a newer public version of the technical documentation since v1.12 that we could find.
Get unstuck
If an error is blocking a buyer's payment, our FBR Digital Invoicing setup service in Islamabad and Rawalpindi includes help with rejected invoices, and starts with a free ATL status check. We work via PRAL and are not affiliated with FBR. New to DI? Start with the step-by-step setup guide. For ordinary invoices outside the sales tax system, the free invoice generator is enough.
Frequently asked questions
What does FBR error 0401 mean?
The token sent with the invoice is not authorised for the seller NTN or CNIC on the invoice, or the NTN/CNIC has the wrong number of digits. Use the token issued in IRIS for that exact NTN, and make sure you are not using a sandbox token in production.
Why do I get HTTP 401 Unauthorized from the FBR DI API?
Usually the server's IP address is not whitelisted yet, the token belongs to the other environment (sandbox vs production), or the token was pasted with extra spaces. Wait for PRAL to approve the IP, then check the token.
Why was my invoice rejected even though the header said valid?
The header status can be 00 while an item is invalid. An invoice only succeeded if it has an FBR invoice number and every item's status is 00. Check the item-level errors.
Should I just post the invoice again after a timeout?
Not blindly. FBR may have already issued a number. Search for it in the IRIS invoice dashboard first, and cancel any duplicate within 72 hours.
Keep reading
- FBR Digital Invoicing: A Step-by-Step Setup Guide for Small BusinessesWho must integrate, the deadlines, and every step from logging in to IRIS to posting your first live invoice through PRAL, FBR's free licensed integrator.
- HS Codes (PCT Codes) for FBR Invoices: How to Find the Right OneA practical way to choose the 8-digit PCT code for each item you sell, match it to the right unit of measure, and stop FBR rejecting your invoices.
- Sales Tax Invoice Format in Pakistan (2026): Required FieldsA field-by-field checklist for a valid sales tax invoice in Pakistan under the Digital Invoicing rules, with a worked example and the mistakes buyers reject.