Error Handling

The MarketSage API uses standard HTTP status codes and returns detailed error information in JSON format.

Error Response Format

{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": {
      "field": "email",
      "reason": "Invalid format"
    }
  }
}

HTTP Status Codes

Common Error Codes

VALIDATION_ERROR

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid email address",
  "details": {
    "field": "email",
    "reason": "Email format is invalid"
  }
}

RESOURCE_NOT_FOUND

{
  "code": "RESOURCE_NOT_FOUND",
  "message": "Contact not found"
}

DUPLICATE_RESOURCE

{
  "code": "DUPLICATE_RESOURCE",
  "message": "Contact with this email already exists"
}

RATE_LIMIT_EXCEEDED

{
  "code": "RATE_LIMIT_EXCEEDED",
  "message": "Rate limit exceeded",
  "retry_after": 60
}

Handling Errors

async function apiRequest(url, options) {
  try {
    const response = await fetch(url, options);
    const data = await response.json();

    if (!data.success) {
      switch (data.error.code) {
        case 'VALIDATION_ERROR':
          console.error('Validation failed:', data.error.details);
          break;
        case 'RATE_LIMIT_EXCEEDED':
          const retryAfter = data.error.retry_after || 60;
          await sleep(retryAfter * 1000);
          return apiRequest(url, options); // Retry
        case 'UNAUTHORIZED':
          throw new Error('Invalid API key');
        default:
          console.error('API error:', data.error.message);
      }
    }

    return data;
  } catch (error) {
    console.error('Network error:', error);
    throw error;
  }
}

Next Steps