IPO Guruji - IPO Data API for India

The IPO Guruji API uses standard HTTP status codes and returns consistent error responses with structured error codes. This page describes the error format and lists all possible error codes.

Error Response Format

All error responses follow a consistent JSON structure:

Error Response Structure400

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "documentation": "https://docs.ipoguruji.com/errors/ERROR_CODE",
    "details": {}
  },
  "disclaimer": "Data aggregated from publicly accessible sources. Not investment advice.",
  "timestamp": "2026-02-09T14:30:00.000Z",
  "requestId": "req_abc123def456"
}

Field	Type	Description
`success`	boolean	Always false for error responses
`error.code`	string	Machine-readable error code (e.g., AUTH_001)
`error.message`	string	Human-readable error description
`error.documentation`	string	Link to relevant documentation for this error
`error.details`	object \| undefined	Additional context (e.g., validation errors, retry information)
`timestamp`	string	ISO 8601 timestamp of the error
`requestId`	string	Unique request ID for debugging and support

HTTP Status Codes

The API uses standard HTTP status codes to indicate success or failure:

Status	Name	Description
200	OK	Request succeeded
201	Created	Resource created successfully
400	Bad Request	Invalid request parameters or body
401	Unauthorized	Missing or invalid API key
403	Forbidden	Feature not available on your plan
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Unexpected server error
503	Service Unavailable	Temporary maintenance or overload

Error Codes Reference

Authentication Errors (AUTH_*)

Code	HTTP	Description	Resolution
`AUTH_001`	401	Missing or invalid API key	Include a valid X-API-Key header with your request
`AUTH_002`	401	API key not found or revoked	Generate a new API key from your dashboard
`AUTH_003`	401	API key expired	Generate a new API key from your dashboard
`AUTH_004`	403	Account suspended	Contact support at support@ipoguruji.com

Validation Errors (VAL_*)

Code	HTTP	Description	Resolution
`VAL_001`	400	Invalid request parameters	Check the details field for specific validation errors
`VAL_002`	400	Invalid request body	Ensure the request body matches the expected schema
`VAL_003`	400	Invalid query parameter value	Check allowed values for the query parameter

Validation Error Example400

{
  "success": false,
  "error": {
    "code": "VAL_001",
    "message": "Invalid request parameters",
    "documentation": "https://docs.ipoguruji.com/errors/VAL_001",
    "details": {
      "validationErrors": {
        "limit": ["limit must be between 1 and 100"],
        "status": ["Invalid status value. Allowed: upcoming, open, closed, listed, withdrawn"]
      }
    }
  },
  "disclaimer": "Data aggregated from publicly accessible sources. Not investment advice.",
  "timestamp": "2026-02-09T14:30:00.000Z",
  "requestId": "req_v4l1d3r0r1"
}

Not Found Errors (NOT_*)

Code	HTTP	Description	Resolution
`NOT_001`	404	Resource not found	Verify the slug or ID exists. Use the list endpoint to find valid identifiers.
`NOT_002`	404	Endpoint not found	Check the API endpoint URL for typos

Rate Limit Errors (RATE_*)

Code	HTTP	Description	Resolution
`RATE_001`	429	Per-minute rate limit exceeded	Wait for the Retry-After period, then retry with exponential backoff
`RATE_002`	429	Daily quota exceeded	Wait until the next day or upgrade your plan for a higher quota

Plan Errors (PLAN_*)

Code	HTTP	Description	Resolution
`PLAN_001`	403	Feature not available on current plan	Upgrade to a plan that includes this feature
`PLAN_002`	403	Webhook limit reached for your plan	Delete unused webhooks or upgrade your plan

Server Errors (SRV_*)

Code	HTTP	Description	Resolution
`SRV_001`	500	Internal server error	Retry the request. If the error persists, contact support with the requestId.
`SRV_002`	503	Service temporarily unavailable	The service is under maintenance. Retry after a few minutes.

Handling Errors in Code

Always check the success field and handle errors appropriately:

Error Handling Example

async function fetchIPO(slug, apiKey) {  const response = await fetch(    `https://api.ipoguruji.com/v1/ipos/${slug}`,    { headers: { 'X-API-Key': apiKey } }  );  const result = await response.json();  if (!result.success) {    const { code, message } = result.error;    switch (code) {      case 'AUTH_001':      case 'AUTH_002':        throw new Error('Authentication failed. Check your API key.');      case 'NOT_001':        return null; // Resource not found      case 'RATE_001':        // Wait and retry        const retryAfter = result.error.retryAfter || 30;        await new Promise(r => setTimeout(r, retryAfter * 1000));        return fetchIPO(slug, apiKey); // Retry      case 'PLAN_001':        throw new Error('Upgrade your plan to access this feature.');      case 'VAL_001':        console.error('Validation errors:', result.error.details);        throw new Error(`Invalid request: ${message}`);      default:        throw new Error(`API error (${code}): ${message}`);    }  }  return result.data;}

Debugging Tips

Save the requestId

Every response includes a unique requestId. Include this when contacting support for faster resolution.

Check the details field

For validation errors (VAL_*), the error.details object contains field-level error messages that indicate exactly what went wrong.

Follow the documentation link

Each error includes a documentation URL that links to specific guidance for resolving the error.