WhiteBooks API Error Catalog

Every error code returned by the WhiteBooks GST, e-Invoice, e-Way Bill, and KSA APIs — with the HTTP status, root cause, and recommended fix. Stable across API versions per our semver + 90-day deprecation policy.

Error response shape

{
  "error": {
    "code":       "WB-GST-1001",
    "status":     400,
    "message":    "Human-readable error description.",
    "details":    { ... optional field-level context },
    "request_id": "req_2k9j4h…",
    "doc_url":    "https://whitebooks.in/docs/errors#wb-gst-1001"
  }
}

Authentication (4xx)

Code HTTP Cause & fix
WB-AUTH-1001 401 Missing or malformed Authorization header. Fix: include Authorization: Bearer <access_token> on every request.
WB-AUTH-1002 401 Access token expired (default 1 hour). Fix: exchange your refresh token via POST /oauth/token.
WB-AUTH-1003 403 Tenant lacks scope for this endpoint. Fix: check your subscription tier or upgrade to a tier that includes this API.
WB-AUTH-1004 403 IP address not in tenant allow-list. Fix: add caller IP to allow-list in dashboard → Security → API IP allow-list.

Validation (4xx)

Code HTTP Cause & fix
WB-VAL-2001 400 Required field missing in request body. Fix: refer to details.field in the error payload — it names the missing key.
WB-VAL-2002 422 GSTIN format invalid. Fix: confirm 15-character GSTIN matches PAN-state pattern. Use /api/v1/gstin/verify to validate before posting.
WB-VAL-2003 422 Invoice line items don't roll up to header total. Fix: ensure sum(line.taxable_value) equals header.taxable_value within 0.05 INR rounding.
WB-VAL-2004 409 Duplicate invoice number for the same financial year. Fix: use a unique doc_no per FY per GSTIN, or pass Idempotency-Key header to safely retry.

Rate limiting (429)

Code HTTP Cause & fix
WB-RATE-3001 429 Per-token request rate exceeded for current tier. Fix: respect Retry-After header (seconds) and exponential-backoff retry. Upgrade tier for higher quota.
WB-RATE-3002 429 Daily quota exceeded. Fix: rate-limit headers expose X-RateLimit-Remaining-Day — schedule bulk jobs across a 24h window.

Upstream GSTN / NIC (502, 503, 504)

Code HTTP Cause & fix
WB-GOV-4001 502 GSTN upstream returned a malformed response. Fix: WhiteBooks auto-retries 3x with backoff — no action needed unless persistent. Check /status for incidents.
WB-GOV-4002 503 NIC e-Invoice / e-Way Bill portal under maintenance. Fix: WhiteBooks queues the request and replays automatically once NIC is back. No client retry needed.
WB-GOV-4003 504 GSTN upstream timeout (> 30 s). Fix: WhiteBooks marks the call as pending in the queue; subscribe to the invoice.upstream_resolved webhook for the final outcome.

Recommended retry behaviour

Last updated: 2026-06-03 · See /changelog for breaking-change history · Questions? sales@whitebooks.in

Schedule Demo