Error Codes

When an API request fails, MarketPulse returns a structured error response with a machine-readable code and human-readable message.

Error Response Format

All error responses follow this structure:

{
  "success": false,
  "error": {
    "code": "AUTH_INVALID_TOKEN",
    "message": "The provided API token is invalid."
  },
  "meta": {
    "requestId": "req_abc123",
    "timestamp": "2026-04-15T10:30:00Z"
  }
}

Error Code Reference

AUTH_INVALID_TOKEN401

The provided API token is invalid or malformed.

Solution: Verify the token value and prefix.

AUTH_EXPIRED_TOKEN401

The API token has expired.

Solution: Generate a new API token from your dashboard.

AUTH_MISSING_TOKEN401

No Authorization header was provided.

Solution: Include a Bearer token in every request.

RATE_LIMIT_EXCEEDED429

You exceeded the rate limit for the current window.

Solution: Reduce request frequency or move to a higher plan.

INVALID_SYMBOL400

One or more requested symbols are not valid.

Solution: Check symbol format and available instruments.

INVALID_MARKET400

The specified market does not exist.

Solution: Use stock, forex, metals, indices, crypto, or funds.

INVALID_PARAMETER400

A required parameter is missing or invalid.

Solution: Review the reference for required parameters.

RESOURCE_NOT_FOUND404

The requested resource does not exist.

Solution: Verify the endpoint URL and identifiers.

INTERNAL_ERROR500

An unexpected error occurred on the server.

Solution: Retry the request and contact support if it persists.

SERVICE_UNAVAILABLE503

The service is temporarily unavailable.

Solution: Wait and retry with exponential backoff.

Error Handling Best Practices

Always check the success field first. This indicates whether the request was successful.
Use the error code for programmatic handling. Match against error codes to provide appropriate fallback behavior.
Implement exponential backoff for 429 and 5xx errors. Wait increasingly longer between retry attempts.
Log the requestId for debugging. Include it when contacting support about a specific request.

Error Handling Example

async function fetchQuotes(symbols) {
  const response = await fetch(
    `https://api.marketpulse.io/v1/quotes/latest?symbols=${symbols}`,
    { headers: { 'Authorization': `Bearer ${API_TOKEN}` } }
  );
  
  const data = await response.json();
  
  if (!data.success) {
    switch (data.error.code) {
      case 'AUTH_INVALID_TOKEN':
      case 'AUTH_EXPIRED_TOKEN':
        // Redirect to re-authenticate
        throw new Error('Authentication required');
      
      case 'RATE_LIMIT_EXCEEDED':
        // Wait and retry
        await sleep(1000);
        return fetchQuotes(symbols);
      
      case 'INVALID_SYMBOL':
        // Handle invalid input
        throw new Error(data.error.message);
      
      default:
        // Log and surface generic error
        console.error('API Error:', data.error);
        throw new Error('Failed to fetch quotes');
    }
  }
  
  return data.data;
}

Need Help?

If you're encountering persistent errors or need help debugging your integration, review the authentication rules and dashboard token status first.

Security