Essentials

Errors & Status Codes

The APIs use conventional HTTP status codes and return a consistent JSON error envelope, so you can handle failures the same way across every endpoint.

Error envelope

Every error response shares the same shape. Always log the transaction_id — it’s what support needs to trace a request.

2 "code": "GSTIN_INVALID",

3 "message": "The supplied GSTIN failed checksum validation.",

4 "transaction_id": "b1f4c2a0-9d3e-4f21-8c77-2a1e9f0b3d44",

5 "timestamp": "2026-06-14T09:42:11Z"

HTTP status codes

Code	Meaning	When it happens
`200`	OK	The request succeeded.
`400`	Bad Request	Malformed JSON or a missing required field.
`401`	Unauthorized	Token missing, invalid, or expired.
`403`	Forbidden	Key lacks permission or IP is not allow-listed.
`404`	Not Found	The resource or entity does not exist.
`422`	Unprocessable Entity	Validation failed (e.g. invalid GSTIN or IFSC).
`429`	Too Many Requests	You exceeded your rate limit.
`503`	Service Unavailable	Upstream GSTN/NIC system is temporarily down.

Common error codes

Code	Description
`GSTIN_INVALID`	GSTIN failed format or checksum validation.
`TOKEN_EXPIRED`	Access token has passed its one-hour lifetime.
`RATE_LIMITED`	Request quota exceeded for the current window.
`DUPLICATE_IRN`	An IRN already exists for this invoice document.
`UPSTREAM_TIMEOUT`	The government system did not respond in time.

Retry transient failures

Treat 429, 503, and UPSTREAM_TIMEOUT as retryable. Use exponential backoff and respect the reset window — don’t hammer a failing upstream.

PreviousAuthentication