API Error Codes

Every error response from the WhiteBooks API carries { status, code, message, requestId }. Codes group into four tiers: 4xx (your request was malformed), 5xx-WB (a WhiteBooks gateway issue), 5xx-IRP (upstream IRP / NIC / GSTN issue, auto-retried), and 4xx-GSTN (your GSTIN / data was rejected upstream).

Response format

{
  "status":    422,
  "code":      "INV_GSTIN_FORMAT",
  "message":   "GSTIN must be 15 characters: 2-digit state + 10-char PAN + 1-char entity + 1-char Z + 1-char checksum.",
  "field":     "buyer.gstin",
  "requestId": "req_abc123def456",
  "timestamp": "2026-05-27T08:30:00Z"
}

Categories

HTTPCategoryMeaningRetry?
400Client errorMalformed request payloadNo — fix the request
401AuthBearer token missing or expiredRefresh token then retry
403PermissionToken valid but lacks scope for this endpointNo — talk to sales
422ValidationField-level validation failedNo — fix the field
429Rate limitExceeded your tier's rate limitYes — honour Retry-After header
500WhiteBooks gatewayTransient internal issue at our edgeYes — exponential backoff
502 / 503 / 504Upstream (IRP / NIC / GSTN)Government portal slow or downYes — SDK retries 3× automatically

Selected error codes

CodeHTTPMeaning
INV_GSTIN_FORMAT422GSTIN doesn't match the 15-char format
GSTIN_INACTIVE422GSTIN is cancelled or suspended in the GSTN database
IRN_DUPLICATE409IRN already generated for this invoice number + GSTIN + FY
IRN_CANCEL_WINDOW_EXPIRED42224-hour IRP cancellation window has passed
EWB_VEHICLE_REQUIRED422Part-B (vehicle) must be set before EWB generation
EWB_EXPIRED422e-Way Bill has expired and cannot be extended
RATE_LIMIT_EXCEEDED429Slow down. Honour the Retry-After response header.
UPSTREAM_TIMEOUT504GSTN / IRP / NIC didn't respond within our gateway window. SDK retries automatically.

Webhook delivery errors

We attempt webhook delivery 5 times over 24 hours (1m → 5m → 30m → 2h → 12h). After 5 failures the event is moved to dead-letter and surfaced in the dashboard. Webhook receivers must respond with HTTP 200 within 10 seconds.

Authentication →OAuth 2.0 + bearer token flow Rate limits →Per-tier numbers + 429 handling Retry logic →How the SDK handles transient errors Status →Live incident history

Part of the WhiteBooks developer documentation cluster. See /llms.txt for the full machine-readable site index. Last updated 27 May 2026.

Schedule Demo