Quickstart

This guide walks you from sandbox key → first authenticated call → handling a real error response. We use the GST Rate (Jewellery) API as the worked example because its responses are short and the schema is representative.

1. Get a sandbox key

Email prafful@sahayakonline.co.in with:

• Company name + GSTIN (if registered)
• One-line use case
• Tech contact email (where the key lands)

You'll receive a key like sk_sandbox_<32-char-random> within four working hours. Sandbox keys never expire and never roll into a paid plan automatically.

2. Make your first call

cURL

curl -sS https://gstjewel.sahayakonline.co.in/v1/gst/jewel/rate \
  -H "Authorization: Bearer sk_sandbox_REPLACE_WITH_YOUR_KEY" \
  -H "Accept: application/json"

Python

import requests, os

resp = requests.get(
    "https://gstjewel.sahayakonline.co.in/v1/gst/jewel/rate",
    headers={
        "Authorization": f"Bearer {os.environ['SAHAYAK_KEY']}",
        "Accept": "application/json",
    },
    timeout=10,
)
resp.raise_for_status()
print(resp.json())

Node.js

const fetch = (await import('node-fetch')).default;

const resp = await fetch('https://gstjewel.sahayakonline.co.in/v1/gst/jewel/rate', {
  headers: {
    'Authorization': `Bearer ${process.env.SAHAYAK_KEY}`,
    'Accept': 'application/json',
  },
});
const data = await resp.json();
console.log(data);

Expected shape:

{
  "spec_ref": "spec_12_GST_Rate_Jewellery_API",
  "endpoint": "/v1/gst/jewel/rate",
  "method": "GET",
  "results": [
    {
      "id": "gold_22k_jewellery",
      "name": "Gold (22-carat) jewellery",
      "fields": { "hsn": "7113", "rate_pct": 3, "effective_from": "2025-04-01" }
    }
  ],
  "meta": {
    "fixture_mode": true,
    "note": "fixture-mode response — replace with a live scraper before shipping to a paying customer."
  }
}

The meta.fixture_mode: true flag is your assertion handle. In CI, fail tests if you see meta.fixture_mode == true against a production endpoint.

3. Handle errors

401 Unauthorized

Header missing, malformed, or wrong key. Check that the Authorization: Bearer … header is present and the key matches the one issued. Sandbox keys do not work against live tier endpoints — request a live tier upgrade first.

429 Rate Limited

Sandbox tier: 30 requests/min/key. Starter: 300 r/m. Growth: 1,500 r/m. Scale: custom. Response includes Retry-After: <seconds>. Implement exponential backoff with jitter.

503 Upstream Unavailable

The regulator portal returned non-2xx or timed out. Sahayak retries thrice with backoff before surfacing 503. Fixture-mode endpoints rarely 503; live endpoints occasionally do during regulator portal maintenance windows.

200 with meta.fixture_mode: true on a live-priced endpoint

This means the live scraper is degraded and we're serving the last-known-good fixture. Log it and continue — your bill is not charged for fixture-fallback responses.

4. Idempotency

All read endpoints are naturally idempotent. Write endpoints (POST/PATCH — only on a few APIs like consent flows) honor an Idempotency-Key header: pass any UUIDv4, and we de-dup retries within a 24-hour window.

5. Pagination

Endpoints returning lists include meta.next_cursor when a next page exists. Pass it back as ?cursor=…. Default page size is 25; max 200.

What's next?

• Authentication — Key rotation, environment separation, and the 90-day rotation policy.
• Status & SLA — Uptime targets per tier, planned-maintenance windows, and incident communication.