Errors & Status Codes (400, 401, 429)
http://52.66.240.39:8000Response 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)
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:
{
"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"
}{
"data": {
/* Direct JSON object containing record fields or table metadata schema */
},
"status": "success"
}Total daily credit allowance from your active subscription plan and real-time remaining credits today.
Aggregate credits consumed today (used_credits) and credits billed for this specific query (credit_used).
For list queries, contains results with count, next, and previous.
Guaranteed execution state ("success" on 2xx).
?page=1&page_size=242. IEX Market Endpoints โ Error Handling & Status Codes Specification
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.
/api/v1/iex/dam//api/v1/iex/gdam//api/v1/iex/state-dam//api/v1/iex/state-gdam/1. Authentication & API Key Gate
Authentication is required via Developer API Key passed in the HTTP header (X-API-Key: gm_live_...).
No X-API-Key header was provided in the HTTP request.
{
"detail": "Authentication credentials were not provided."
}The X-API-Key header value does not begin with the required gm_live_ prefix.
{
"detail": "Invalid API key format."
}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."
}2. Subscription Expiry & Origin Check
Returned when the user's paid subscription (Developer or Pro) has reached its billing cycle expiration without renewal, or was explicitly cancelled:
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."
}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."
}3. Rate Limiting & Plan Quotas
Retry-After HTTP header.Header: Retry-After: <seconds>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)."
}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."
}4. Date, Query & Filter Validations
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:
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."
]
}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."
]
}Malformed date string passed (e.g. ?date=2026-02-31 or ?start_date=invalid).
{
"date": [
"Enter a valid date."
]
}Non-integer passed to hour or time_block (e.g. ?hour=noon).
{
"hour": [
"Enter a whole number."
]
}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
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:
2012-04-01 โ Present (Today)