GST Verification API Error Codes: A Troubleshooting Guide

HTTP status codes, cause and fix

Start with the HTTP layer. This is the transport-level signal your HTTP client sees before your code ever looks at the response body:

A "does not exist" GSTIN is not a transport error

This is the distinction that trips up the most integrations, so it is worth stating plainly: a well-formed GSTIN that has never been issued, or that no longer exists, is a successful API call with a not-found result — it is not the same thing as a 404, a 500, or any other transport-level failure. The HTTP request succeeded. The API did exactly what it was asked to do: it queried the live record and reported back that none exists for that number. Code that treats this outcome as an exception to catch, log, and alert on will generate constant false-positive noise, because "this GSTIN doesn't exist" is an entirely normal, expected answer — it happens every time someone mistypes a digit or tries to verify a number that was never real in the first place.

Upstream GSTN errors: SWEB_9035 and friends

Underneath the API's own response shape sits the government's own GSTN system, which has its own family of internal error codes. The one you will see most often is SWEB_9035 — "Invalid GSTIN / UID", which is GSTN's own way of reporting exactly the not-found case described above: the number is structurally valid but does not correspond to any taxpayer on record. When this code surfaces, it confirms the lookup reached the government system and got a definitive "no match" answer, rather than failing somewhere in between.

Other upstream error families exist for GSTN-side maintenance windows, temporary unavailability, and malformed queries, but SWEB_9035 is the one worth knowing by name because it is the one you will encounter routinely in normal usage — every time a customer, vendor, or user submits a GSTIN that turns out to be fake or mistyped.

Why a failed validation does not cost you a credit

It matters, practically, where in the pipeline a request fails. A request rejected for basic validation reasons — a malformed GSTIN that fails the checksum before it is even sent upstream, a missing or invalid API key, a request to the wrong path — never reaches a real lookup against GSTN records, and this API does not charge a verification credit for it. You are only billed for a completed lookup: one where the API actually queried the record and returned a result, whether that result is an active taxpayer, a cancelled registration, or a genuine not-found. This is a meaningful distinction if you are validating user-entered GSTINs at scale — client-side format checks (using the checksum described in our GSTIN format guide) filter out typos for free, before they ever touch your credit balance.

A sane error-handling pattern

Putting it together, a reasonable client-side handler treats HTTP status, the response body's own status field, and retryability as three separate questions:

async function verifyGstin(gstin) {
  const res = await fetch(`https://gstinapi.com/api/get-taxpayer-info/${gstin}`, {
    headers: { 'X-API-Key': process.env.GSTINAPI_KEY },
  });

  if (res.status === 401 || res.status === 403) {
    throw new Error('Check your API key and account permissions.');
  }

  if (res.status === 402) {
    throw new Error('Out of verification credits — upgrade your plan.');
  }

  if (res.status === 429) {
    const retryAfter = Number(res.headers.get('Retry-After')) || 5;
    await sleep(retryAfter * 1000);
    return verifyGstin(gstin); // retry once, respecting the server's timing
  }

  if (res.status >= 500) {
    throw new RetryableError('Upstream/API error — safe to retry with backoff.');
  }

  if (res.status === 400 || res.status === 422) {
    throw new Error('GSTIN is malformed — check format before calling.');
  }

  const data = await res.json();

  if (data.status === 'not_found') {
    // Not an error: a successful call, no matching taxpayer.
    return { exists: false };
  }

  return { exists: true, ...data };
}

Notice that the "not found" branch sits after a successful HTTP response, not inside the error handling at all — that placement is the whole point. For the retry logic itself, including how long to wait and how to add jitter, see our detailed rate limits, retries and webhooks guide.

Frequently asked questions