FBR Digital Invoicing API Error Codes : Complete Reference & Fixes
If your ERP or POS system is returning an error code during FBR digital invoicing submission, this page has it. Every code below comes directly from FBR/PRAL’s own official technical specification for the Digital Invoicing API — not a paraphrase, not a guess.
HTTP-Level Status Codes (check this first)
| Code | Meaning | What to do |
|---|---|---|
| 200 | OK — request succeeded | No action needed |
| 401 | Unauthorized | Your security token is missing, expired, or malformed — regenerate it and check the “Bearer” prefix in your Authorization header |
| 500 | Internal Server Error | This is an FBR/PRAL-side issue — contact their administrator; not something you can fix on your end |
Most Common Errors (Sales Invoices)
| Code | What FBR Returns | What It Actually Means / Fix |
|---|---|---|
| 0001 | Seller not registered for sales tax | Your seller NTN/registration number isn’t valid in FBR’s system — verify it’s correctly registered before resubmitting |
| 0002 | Invalid Buyer Registration No or NTN | Buyer’s registration number must be exactly 13 digits, or NTN must be 7 or 9 digits — check formatting |
| 0003 / 0011 | Invalid or missing invoice type | Confirm you’re sending a valid type: Sales Invoice, Purchase Invoice, Debit Note, or Credit Note |
| 0005 / 0043 | Invalid date format | FBR requires strict YYYY-MM-DD format (e.g., 2026-07-27) — a common integration mistake |
| 0019 / 0044 | HS Code missing | Every line item needs a valid HS Code — cross-check against FBR’s HS Code reference API |
| 0020 / 0046 | Rate field missing or invalid | Pull the correct rate from FBR’s Rate reference API rather than hardcoding it |
| 0052 | HS Code doesn’t match sale type | The HS Code you’re using isn’t valid for the sale type selected — verify the pairing against FBR’s reference data |
| 0079 | Rate not allowed above sales threshold | If sale value exceeds PKR 20,000, a 5% rate is not permitted — this is a business-rule check, not a bug |
| 0088 | Invalid invoice number format | Invoice numbers must be alphanumeric, with hyphens only between alphanumeric segments (e.g., Inv-001) |
| 0300 | Invalid decimal value | One of your numeric fields (discount, tax, quantity, etc.) has a formatting issue — check for stray characters or wrong decimal places |
Most Common Errors (Purchase Invoices)
| Code | What FBR Returns | What It Actually Means / Fix |
|---|---|---|
| 0114 | Buyer not registered for sales tax | Buyer’s registration/NTN isn’t valid — verify before resubmitting |
| 0115 / 0118 | Invalid Seller Registration No or NTN | Check digit format (13-digit registration or 7/9-digit NTN); special characters aren’t allowed |
| 0119 | Wrong purchase type selected | The purchase type doesn’t match what’s expected for this invoice — recheck against FBR’s purchase type list |
| 0146 | Invalid data type | You’re sending a string where FBR expects a decimal value — check your field types |
| 0147 | Invalid date format | Same fix as 0005/0043 — use YYYY-MM-DD |
| 0156 | Invalid NTN/Registration Number | Format or value doesn’t match FBR’s records |
Debit/Credit Note-Specific Errors
| Code | What FBR Returns | Fix |
|---|---|---|
| 0026 | Invoice Reference No. required | Debit/credit notes must reference the original invoice number |
| 0029 / 0035 | Date must be ≥ original invoice date | Note date can’t be earlier than the invoice it’s correcting |
| 0034 | Note must be within 180 days | Debit/credit notes can only be filed within 180 days of the original invoice |
| 0064 | Reference invoice already exists | A credit note has already been applied to this invoice — duplicate submission |
A Note on Reliability
Most “mystery” errors trace back to one of three root causes:
- Reference data mismatches — HS Code, rate, or UOM values not pulled fresh from FBR’s reference APIs
- Format issues — dates, invoice numbers, or NTN/registration numbers not matching FBR’s exact expected format
- Business rule violations — valid data that still breaks a specific rule (e.g., rate thresholds, sector-specific restrictions)
A properly configured integration validates data against FBR’s live reference APIs (province, HS Code, rate, UOM) before submission, rather than relying on hardcoded values that go stale as FBR updates its reference tables.
Quick Troubleshooting Checklist (Supplemental)
Before resubmitting an invoice to the FBR Digital Invoicing API, verify the following:
- ✅ Security token is valid and not expired
- ✅ Authorization header includes the
Bearerprefix - ✅ Invoice date uses
YYYY-MM-DD - ✅ Seller and buyer NTN/registration numbers are correctly formatted
- ✅ HS Codes match the selected sale type
- ✅ Tax rates are retrieved from the latest FBR reference APIs
- ✅ Invoice number follows FBR formatting rules
- ✅ Numeric fields contain valid decimal values
- ✅ Debit/Credit Notes reference the original invoice
- ✅ Business rules (thresholds and validation rules) are satisfied
Related Resources
- Complete FBR Digital Invoicing API Guide
- FBR Sales Tax Invoice Validation Rules
- ERP Integration with FBR Digital Invoicing API
- POS Integration with FBR Digital Invoicing
Suggested External References
- PRAL Digital Invoicing API Technical Specification
- https://fbr.gov.pk/
- https://pral.com.pk/
- https://iris.fbr.gov.pk/
- https://download1.fbr.gov.pk/
Frequently Asked Questions (Supplemental)
What is the most common reason for FBR Digital Invoicing API failures?
Many submission failures are caused by outdated reference data, incorrect formatting, or business rule validation errors.
Why does FBR reject an invoice with a valid NTN?
The NTN may be correctly formatted but may not match FBR’s registration records or the required registration type.
Why should ERP systems use FBR reference APIs?
Using live reference APIs helps ensure HS Codes, tax rates, and other reference values remain current as FBR updates its data.
What date format does the FBR Digital Invoicing API require?
The API requires the YYYY-MM-DD format.
Why am I getting an “Invalid decimal value” error?
This typically indicates that one or more numeric fields contain an invalid decimal format or unexpected characters.
Can I issue a credit note for any invoice?
Credit notes must satisfy FBR validation rules, including referencing the original invoice and meeting the applicable submission requirements.
Need Help Resolving an Error?
If you’re seeing an error code not listed here, or need help debugging a failed integration, contact NatureTech’s support team — as an FBR-licensed integrator, we work with these error codes daily.
