eTIMS Troubleshooting Guide

Resolutions for common KRA eTIMS invoice signing errors and validation issues.

Error Reference

1. ERR_INVALID_BUYER_PIN

• Cause: The customer's KRA PIN is formatted incorrectly or does not exist in the KRA iTax database.
• Resolution: Check the PIN format (A000000000X or P000000000X). If selling to an unregistered individual, leave the PIN field empty to issue a B2C retail receipt.

2. ERR_UNSPSC_MISSING

• Cause: One or more product line items in the invoice do not have an assigned UNSPSC code.
• Resolution: Open each product in the invoice, navigate to the eTIMS tab, select a valid UNSPSC code, and re-post the invoice.

3. ERR_KRA_GATEWAY_TIMEOUT

• Cause: Temporary network timeout or maintenance on the KRA eTIMS server.
• Resolution: The invoice is safely stored in the PENDING_SYNC state. The background Celery worker will automatically retry signing every 2 minutes.