API Documentation

Errors & Status Codes (400, 401, 429)

Architecture & StandardsREST v1.0 Standard
API Base:http://52.66.240.39:8000

Response Envelopes, Error Formats & Clearing Schedules

Every GridMap REST endpoint adheres to a strict envelope contract. Responses are uniformly structured across list collections, single entity retrievals, table metadata, field validations, and rate limit throttling.

1. Universal Response Envelope Contract (IEX)

Unified Schema Specification

All GridMap APIs across India (IEX DAM, GDAM, State DAM & State GDAM) return data wrapped inside a single, standardized root envelope. SDKs and algorithmic pipelines only need to implement one universal response handler:

Paginated List Endpoints (/list/)GET Collection
{
  "total_credits": 100,
  "used_credits": 1,
  "remaining_credits": 99,
  "credit_used": 1,
  "data": {
    "count": "<integer: total_records>",
    "next": "<string: next_page_url | null>",
    "previous": "<string: prev_page_url | null>",
    "results": [
      {
        /* Array of market records (interval clearing, state prices, summaries) */
      }
    ]
  },
  "status": "success"
}
Single Entity & Meta Endpoints (/uuid/ or /table-meta/)GET Detail / Meta
{
  "data": {
    /* Direct JSON object containing record fields or table metadata schema */
  },
  "status": "success"
}
total_credits / remaining_credits
Integer | Plan Rate Limit

Total daily credit allowance from your active subscription plan and real-time remaining credits today.

used_credits / credit_used
Integer | Usage Accounting

Aggregate credits consumed today (used_credits) and credits billed for this specific query (credit_used).

data
Object | Paginated Collection

For list queries, contains results with count, next, and previous.

status
"success" | "error"

Guaranteed execution state ("success" on 2xx).

Pagination Parameters:Pass ?page=1&page_size=24
Default: 24 / pageโ€ขMaximum: 100 / page

2. IEX Market Endpoints โ€” Error Handling & Status Codes Specification

Deterministic Error Payloads

All non-200 HTTP error responses across WireGrid IEX market endpoints adhere to deterministic HTTP status codes and structured JSON payloads. This specification documents exception triggers, HTTP headers, exact error schemas, and production error-handling guidelines.

Applicable Endpoints Scope:list/ โ€ข hourly/list/ โ€ข daily/list/ โ€ข monthly/list/ โ€ข yearly/list/
DAM:/api/v1/iex/dam/
GDAM:/api/v1/iex/gdam/
State DAM:/api/v1/iex/state-dam/
State GDAM:/api/v1/iex/state-gdam/
HTTP 401 Unauthorized
1. Authentication & API Key Gate
Security Gate

Authentication is required via Developer API Key passed in the HTTP header (X-API-Key: gm_live_...).

A. Missing Credentials

No X-API-Key header was provided in the HTTP request.

{
  "detail": "Authentication credentials were not provided."
}
B. Invalid Key Format

The X-API-Key header value does not begin with the required gm_live_ prefix.

{
  "detail": "Invalid API key format."
}
C. Revoked / Inactive Key

The API key hash does not match an active key in the database or is_active is set to false.

{
  "detail": "API key is invalid or has been revoked."
}
HTTP 403 Forbidden
2. Subscription Expiry & Origin Check
Plan Status Restriction

Returned when the user's paid subscription (Developer or Pro) has reached its billing cycle expiration without renewal, or was explicitly cancelled:

A. Expired Subscription Plan

Paid subscription expired. Renew plan or downgrade to Free tier in Developer Dashboard.

{
  "detail": "Your Developer plan expired on 2026-11-16. Please renew your subscription or switch to the Free plan in your dashboard to continue using the API."
}
B. Cancelled Subscription Plan

User cancelled paid subscription or payment gateway recurrence halted.

{
  "detail": "Your Pro plan was cancelled on 2026-11-12. Please renew your subscription or switch to the Free plan in your dashboard to continue using the API."
}
HTTP 429 Too Many Requests
3. Rate Limiting & Plan Quotas
Sliding Window Redis Rate Limiter
Every request is evaluated against the user's active Plan limits in Redis. Rate-limited requests return a Retry-After HTTP header.Header: Retry-After: <seconds>
A. Per-Minute Burst Throttle
Tiers: Free: 5/min โ€ข Dev: 30/min โ€ข Pro: 120/min

User exceeded per-minute burst threshold. Header: Retry-After: 45 (seconds until current minute resets).

{
  "detail": "Per-minute rate limit of 30 requests exceeded for your current plan (Developer)."
}
B. Daily Quota Limit Exceeded
Tiers: Free: 100/day โ€ข Dev: 5,000/day โ€ข Pro: 50,000/day

Total daily request count exceeded plan quota. Header: Retry-After: 14250 (seconds until 00:00 UTC).

{
  "detail": "Daily rate limit of 5,000 requests exceeded for your current plan (Developer). Resets at 00:00 UTC."
}
HTTP 400 Bad Request
4. Date, Query & Filter Validations
Field-Level Array Error Format

WireGrid follows standard Django REST Framework conventions: validation errors and tier restrictions return a JSON object containing an array of human-readable error messages keyed by the invalid parameter:

A. Plan History Limit Exceeded (Historical Archive Restriction)

Triggered when querying a historical date older than allowed by your subscription plan (e.g. Free plan querying beyond 7 days of 15-min or daily data).

{
  "date": [
    "Your Free plan allows access to historical data from 2026-11-09 onwards. Please upgrade your subscription plan to access older historical data."
  ]
}
B. QuerySet Inactive Sub

Request bypassed throttle or cache while the subscription is marked inactive/expired.

{
  "subscription": [
    "Your Developer plan expired on 2026-11-16. Please renew your subscription or switch to the Free plan in your dashboard to continue using the API."
  ]
}
C. Invalid Date Format

Malformed date string passed (e.g. ?date=2026-02-31 or ?start_date=invalid).

{
  "date": [
    "Enter a valid date."
  ]
}
D. Invalid Integer Filter

Non-integer passed to hour or time_block (e.g. ?hour=noon).

{
  "hour": [
    "Enter a whole number."
  ]
}
TypeScript Reference
5. Frontend Error Handling Helper (handleApiError)

Integrate this production-ready error-handling helper into your frontend application, Axios/Fetch interceptor, or trading agent to parse GridMap error envelopes deterministically:

export function handleApiError(error: any): string {
  if (!error.response) {
    return "Network error. Please check your internet connection.";
  }

  const { status, data, headers } = error.response;

  // 1. Rate Limit (429)
  if (status === 429) {
    const retryAfter = headers["retry-after"] || 60;
    return data.detail || `Rate limit exceeded. Please wait ${retryAfter} seconds.`;
  }

  // 2. Auth / Plan Expired (401, 403)
  if (status === 401 || status === 403) {
    return data.detail || "Access denied. Please check your credentials or subscription.";
  }

  // 3. Validation / Plan History Restriction (400)
  if (status === 400) {
    if (Array.isArray(data)) return data[0];
    if (typeof data === "object") {
      // Pick first error field (e.g. date, start_date, subscription, hour)
      const firstField = Object.keys(data)[0];
      const fieldError = data[firstField];
      return Array.isArray(fieldError) ? fieldError[0] : fieldError;
    }
  }

  // 4. Page Not Found (404)
  if (status === 404) {
    return data.detail || "Resource not found.";
  }

  return "An unexpected error occurred. Please try again.";
}

3. IEX Auction Clearing Timeline & Settlement Schedule

Daily Schedule

Day-Ahead physical power spot markets execute once per calendar day to clear bids and publish next-day (T+1) delivery schedules. GridMap reconciles and indexes cleared telemetry within 30 seconds of official IEX publication:

๐Ÿ‡ฎ๐Ÿ‡ณIndia โ€” IEX Day-Ahead Auction
DAILY AUTOMATION
TimezoneAsia/Kolkata (IST, UTC+05:30)
Daily Ingestion Pull16:00 IST (4:00 PM) Daily
Delivery Horizon96 Blocks for Day T+1 (00:00 - 24:00)
Market & State DAM / GDAM2012-04-01 โ†’ Present (Today)