Short answer: Read the exact error and first establish whether KRA accepted the original sale. A validation rejection needs a corrected field; a timeout has an unknown outcome; an existing invoice number needs reconciliation. Recover an accepted receipt instead of creating another sale. Correct an accepted invoice through the issuing solution's supported credit-note process.
Start with the Outcome, Then Choose the Fix
| What happened | What you know | Next action |
|---|---|---|
| A field validation error was returned | The message identifies data that was not accepted | Preserve the response, correct the named field and use the original submission's supported retry flow. |
| The connection timed out | The request may have reached KRA; the outcome is unknown | Check the original transaction and receipt before retrying. Keep it pending while the outcome is unresolved. |
| Invoice number already exists | The sequence conflicts with an existing record | Retrieve and compare the existing record. Do not assume the response proves this sale was accepted. |
| KRA accepted the invoice but its data is wrong | The fiscal record already exists | Use the supported correction or credit-note workflow linked to that invoice. |
| KRA accepted the invoice but the PDF is missing | Receipt generation or retrieval still needs attention | Recover the accepted receipt metadata and regenerate/download the PDF; do not resubmit the sale. |
Read the Actual KRA or Gateway Message
KRA OSCU uses resultCd "000" for success. Preserve resultCd, resultMsg and any gateway validation message alongside your local invoice reference, request time and environment. A non-success response is a starting point for diagnosis; its exact meaning depends on the operation and message.
For example, a message such as "Invalid dcAmt for item: 1", with an expected discount of 2000.00 and a submitted value of 1960.00, points to discount arithmetic. The illustrative calculation below shows how to investigate that mismatch.
This reference groups failure categories. It does not assign invented meanings to undocumented numeric error codes or claim every provider uses identical wording.
Worked Example: Invalid dcAmt
Consider an illustrative tax-inclusive line of 2 units at KES 10,000 each with a 10% discount. The gross line is KES 20,000, the discount is KES 2,000 and the discounted total is KES 18,000. A submitted discount of KES 1,960 is inconsistent with that stated rate.
In Risiti's OSCU calculation, the discount is calculated from quantity × unit price. The supply amount is then reduced by that discount. Tax and invoice totals must be rebuilt from the same rounded line amounts. Confirm the price basis and current specification for the integration you use.
| Field | Calculation | Illustrative value |
|---|---|---|
| Gross line | 2 × 10,000 | KES 20,000.00 |
| dcAmt | 20,000 × 10 ÷ 100 | KES 2,000.00 |
| splyAmt / totAmt | 20,000 − 2,000 | KES 18,000.00 |
| taxblAmt, if 16% VAT applies | 18,000 ÷ 1.16, rounded | KES 15,517.24 |
| taxAmt, if 16% VAT applies | 18,000 − 15,517.24 | KES 2,482.76 |
Common eTIMS Error Categories
| Category | Check | Safe correction |
|---|---|---|
| Buyer PIN or name mismatch | Buyer identity against the customer's registered details | Ask the buyer to confirm the correct PIN/name. Do not remove a required business PIN simply to get past validation. |
| Tax type or totals | Item tax code, quantity, price basis, discount and rounded line totals | Use the applicable tax treatment and current code list; make header totals equal the sum of the submitted lines. |
| Date format | The specific field and API contract being sent | Date and datetime fields differ. Risiti's OSCU sales payload uses YYYYMMDD for salesDt and YYYYMMDDHHmmss for cfmDt. A public API may accept a different input format. |
| Item registration | Item code, classification and seller/branch context | Confirm the item is registered in the correct environment and taxpayer context before submitting the sale. |
| Device or communication key | Environment, taxpayer, branch and initialized device | Have the integrator verify configuration. Reinitialize only through the supported onboarding or recovery process. |
| Duplicate invoice number | Existing fiscal record and local sequence history | Reconcile before allocating a new number or claiming success. |
| Network or service failure | Whether KRA received and accepted the original request | Keep the original reference, reconcile the outcome and retry only through a controlled process. |
Resubmit a Rejected Invoice Without Duplicating the Sale
- ✓Find the original invoice and keep its local reference, error and submission timestamp.
- ✓Confirm whether it was rejected before acceptance, remains unresolved, or has an accepted receipt.
- ✓For a confirmed validation rejection, correct the named data through your provider's supported workflow. Recheck all derived totals after a price, quantity, tax or discount change.
- ✓For an unknown outcome, reconcile first. Do not repeatedly click submit or create a replacement sale to clear a pending label.
- ✓After recovery, match the seller, buyer where applicable, invoice identity and totals, then share the accepted receipt.
- ✓If the accepted fiscal record itself is wrong, retain it and the linked correction documents together.
What to Send Your Integrator or KRA Support
- ✓The exact error text/code and when it occurred, including time zone.
- ✓The relevant local invoice reference, KRA/CU reference if returned, and whether this was sandbox or production.
- ✓The operation that failed: onboarding, item registration, sales submission, status recovery or PDF download.
- ✓The affected field values or a redacted request excerpt, plus expected and actual totals.
- ✓What you already checked and whether a retry was attempted.
A Daily Control That Prevents Silent Failures
At the end of the day, review pending, failed and unresolved invoices alongside accepted receipts. Give each exception an owner and next action. Reconcile payment separately: an M-Pesa confirmation does not prove KRA accepted the invoice.
Saved catalogue items reduce repeated entry, but they do not guarantee correct tax treatment forever. Review item changes, rounding rules and buyer details before submission, and check that retries recover the original sale.
Official sources
Official guidance and legislation used to prepare this guide.
Frequently asked questions
Open a question to read the answer.
What does Invalid dcAmt mean?
The submitted discount does not agree with the validator's calculation for the line. Check quantity, price basis, discount rate and rounding, then rebuild supply, tax and invoice totals from the same values.
Should I retry after an eTIMS timeout?
First check the outcome of the original submission. A timeout does not establish that KRA rejected the sale. Recover an accepted receipt or use your provider's controlled retry workflow after reconciliation.
Can I delete the buyer PIN to fix an error?
Do not remove a required business buyer PIN to bypass validation. Confirm the customer's registered details and correct the error through the issuing solution.
Does invoice number already exists prove success?
No. It identifies a conflict that needs reconciliation. Compare the existing KRA record with the original sale before presenting it as accepted.
Can I change an accepted eTIMS PDF?
Editing a PDF does not change KRA's record. Use the issuing solution's supported correction or credit-note process and retain the linked audit trail.
Updated: 14 Sept 2026. Source-check scope and limitations, where recorded, appear below. This guide is not tax or legal advice. Confirm unusual cases with KRA or a qualified tax professional.