GST API Failure Cheatsheet: Handle Every Edge Case

For: A backend engineer at a B2B SaaS company (accounting, ERP, or e-commerce) who owns the GST integration and is debugging a production failure where invoices are getting stuck, GSTINs are validating inconsistently, or return filings are silently rejected — and the NIC/GST portal docs tell them nothing useful

If your GST integration is silently dropping invoices or returning inconsistent GSTIN data, the root cause is almost always the same: you are trusting the HTTP status code. The NIC and GSTN APIs return HTTP 200 on semantic failures and encode the real outcome in an error_cd (or ErrorCode) field inside the JSON body. Your retry logic, alerting, and reconciliation must key off that field — not the transport status. Everything below assumes that contract.

This is a working cheatsheet, not a tutorial. Skim to the section that matches your incident.

The core contract: HTTP status vs. inner error_cd

GSTIN validation API failures

The public /commonapi/v1.1/search endpoint and paid GSP search endpoints do not agree with each other. Cache with care.

• Stale status: A GSTIN cancelled last week may still return Active from cached GSP responses for 24–72 hours. Never cache GSTIN status longer than 24h for tax-critical flows (ITC, e-invoice, e-way bill).
• Legal name mismatch: The name returned by search vs. the name on the actual e-invoice IRN response can differ in punctuation and case. Normalize before comparing — do not fail invoices on cosmetic diffs.
• Composition dealers: dty field returns Composition. Your ITC logic must exclude these; downstream reconciliation will otherwise flag mismatches at GSTR-2B time.
• SEZ / SEZ Developer: ctb field. Requires different invoice type (SEZWP / SEZWOP). Missing this is the most common IRN rejection we see.

E-invoice (IRN) generation errors — the ones docs skip

E-way bill edge cases

• Distance = 0: NIC auto-calculates from PIN-to-PIN. If the PIN pair is unmapped, it returns error_cd 378. Send explicit distance as fallback.
• Vehicle number format: Must be uppercase, no spaces. MH-01-AB-1234 fails; MH01AB1234 passes.
• Part-B update after expiry: Silent failure. The API returns success but the EWB stays expired. Always re-fetch and verify validUpto.

Return filing API (GSTR-1, 3B, IFF) — silent rejections

Filing endpoints are the worst offenders for HTTP 200 + embedded failure. Build your state machine around these four states, not two:

1. Submitted — SAVE call returned success, data staged at GSTN
2. Validation-pending — GSTN async validation running (poll GET status endpoint)
3. Filed — FILE call succeeded AND acknowledgement (ARN) returned
4. Rejected — inner error_cd present at any of the above stages

Common filing error codes:

• RET191106 — Summary and section totals mismatch. Recompute HSN summary from line items server-side, don't trust client aggregates.
• RET13508 — Invoice already uploaded in prior period. Use action = D to delete before re-adding.
• RET11402 — Invalid POS for the invoice type. B2CL requires POS state code, B2B does not.
• RETJSON1001 — Payload schema drift after a GSTN silent update. Version your JSON builder and log the exact payload for every filing call.

Timeout and rate-limit handling

GSP timeouts do not mean the request failed at NIC. This is the single most expensive mistake in GST integrations.

• Set client timeout to 45s minimum for IRN and filing endpoints. NIC's own SLA is 30s but GSP layers add overhead.
• On timeout, do NOT retry blindly. Call the corresponding Get endpoint (GetIRNByDocDetails, GetEwbByIRN, filing status) to check if the request landed. Only retry if confirmed missing.
• Rate limits vary by taxpayer type and API. IRN generation is roughly 1000 requests/GSTIN/hour on most GSPs but drops for turnover slabs above 500Cr due to NIC throttling. Track 429s per-GSTIN, not globally.
• Auth token TTL is 6 hours for most GSPs but they invalidate early on IP change or concurrent session. Cache tokens with a 5h safety margin and handle mid-request 401s by regenerating and retrying exactly once.

Reconciliation: the safety net

Every write API (IRN, EWB, filing) needs a paired reconciliation job that runs at T+1h, T+24h, and T+7d. It compares your internal state to the GSTN state via GET endpoints. Drift is common and is the only way you'll catch the failures your real-time layer swallowed.

• Reconcile IRNs against GetIRNByDocDetails daily for the past 30 days
• Reconcile filed returns against GSTR-2B/2A pull for ITC matching
• Log every error_cd occurrence to a dedicated table — do not let it stay only in application logs

How CodeNicely can help

We built the accounting and GST filing stack behind GimBooks, a YC-backed SMB accounting platform that files returns for tens of thousands of small businesses across India. The specific problems described in this cheatsheet — silent filing rejections, IRN duplicate handling, GSTR-2B reconciliation drift, GSP failover — are ones we've hit and hardened against in production. If your team owns a GST integration that works in staging but bleeds edge cases in production, that's the exact class of problem we've spent years on. See our offerings or digital transformation practice for how we engage.

Frequently Asked Questions

Why does my GST API call return HTTP 200 but the invoice is not registered?

The GSTN and NIC APIs encode semantic failures inside the JSON body via an error_cd or ErrorCode field while keeping the HTTP status at 200. Your handler must check the inner field before treating the call as successful. Standard HTTP-layer retry libraries will not catch this.

How should I retry a GST API call that timed out?

Do not retry the write directly. Call the corresponding GET endpoint first — GetIRNByDocDetails, e-way bill by IRN, or filing status — to check whether the original request actually landed at GSTN. Retry only if the GET confirms the record is missing. Blind retries cause duplicate IRN errors and inflated filing counts.

Why does GSTIN validation return different results on different days?

Most GSPs cache GSTIN search responses for 24–72 hours, and the underlying NIC data itself updates asynchronously after registration or cancellation events. For tax-critical flows, cap your own cache at 24 hours and always re-validate at the invoice date, not the current date, when computing eligibility.

What is the safest way to handle GSTR-1 filing rejections?

Model filing as a four-state machine: submitted, validation-pending, filed, rejected. Poll the status endpoint after every SAVE and FILE call, key off the inner error code, and version your JSON payload builder so you can diff against GSTN schema drift. Store every rejected payload in full for replay.

Can CodeNicely audit our existing GST integration?

Yes. We do targeted reviews of GST, e-invoice, and e-way bill integrations, including error taxonomy, retry semantics, and GSTR-2B reconciliation. Contact CodeNicely for a personalized assessment based on your stack and taxpayer profile.