Troubleshooting

This page covers the most common issues you may encounter with SitemapHost and how to resolve them. For domain-specific problems, see the dedicated DNS Troubleshooting and SSL Troubleshooting pages.

Sitemap Not Loading

Symptom: Visiting https://sitemap.yoursite.com/sitemap.xml returns a 404 or connection error.

Check domain status

Verify your domain is active in the dashboard or via the API:

curl https://dash.sitemaphost.app/api/domains \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

Look for the status and sslStatus fields:

Check sitemap upload

If your domain is active but returns 404, you may not have uploaded a sitemap yet. Upload URLs:

curl -X POST https://dash.sitemaphost.app/api/sitemap/generate \
  -H "Content-Type: application/json" \
  -H "X-API-Key: sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -d '{
    "domain": "sitemap.yoursite.com",
    "urls": [{"loc": "https://yoursite.com/"}]
  }'

Check the correct URL

If you use named sitemaps, the URL will include the name:

• Default sitemap: https://sitemap.yoursite.com/sitemap.xml
• Named sitemap: https://sitemap.yoursite.com/sitemap-pages.xml
• Sitemap index: https://sitemap.yoursite.com/sitemap-index.xml

URLs Not Appearing in Sitemap

Symptom: You uploaded URLs but some are missing from the generated sitemap.

Check validation errors

The upload endpoint validates every URL. Check the API response for errors:

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid URL: 'yoursite.com/page' is not a valid absolute URL."
  }
}

Common validation issues:

Check URL budget

Your plan has a URL limit. If you exceed it, the upload will be rejected:

Check your current usage in the dashboard or contact support to upgrade.

Check named sitemap behavior

When using named sitemaps, each upload replaces the entire named sitemap. If you upload 100 URLs to the "blog" sitemap today and 50 URLs tomorrow, the sitemap will contain only 50 URLs.

To add URLs incrementally, fetch the existing URLs and include them in your next upload.

Rate Limit Errors

Symptom: API returns 429 Too Many Requests.

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Please retry after 30 seconds."
  }
}

Check your plan's limits

Reduce request frequency

• Batch URLs: Send all URLs in a single request rather than one URL per request. The upload endpoint accepts up to 50,000 URLs in one call.
• Use the Retry-After header: The 429 response includes a Retry-After header indicating how many seconds to wait.
• Implement exponential backoff: Start with the Retry-After value and double the wait time on consecutive failures.

async function pushWithRetry(payload, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    const response = await fetch(
      "https://dash.sitemaphost.app/api/sitemap/generate",
      {
        method: "POST",
        headers: {
          "Content-Type": "application/json",
          "X-API-Key": process.env.SITEMAPHOST_API_KEY,
        },
        body: JSON.stringify(payload),
      }
    );

    if (response.status === 429) {
      const retryAfter = parseInt(response.headers.get("Retry-After") || "30");
      console.log(`Rate limited. Waiting ${retryAfter}s...`);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }

    return response.json();
  }

  throw new Error("Max retries exceeded");
}

404 Not Found Errors

Symptom: API endpoints return 404.

Check the base URL

All API requests go to https://dash.sitemaphost.app/api/.... Common mistakes:

Check the endpoint path

Verify you are using the correct endpoint:

Check the domain ID format

Domain IDs use the format domain_xxxxx. If you pass the hostname instead of the ID, you will get a 404:

# Wrong: using hostname
curl -X POST https://dash.sitemaphost.app/api/domains/sitemap.yoursite.com/verify

# Correct: using domain ID
curl -X POST https://dash.sitemaphost.app/api/domains/domain_abc123/verify

Authentication Errors

Symptom: API returns 401 Unauthorized.

See the Authentication page for details on creating and using API keys.

Quick checklist:

1. Is the API key included in the request? (Check X-API-Key or Authorization header)
2. Is the key correct? (No extra whitespace or newlines)
3. Has the key been revoked? (Check the dashboard)
4. Are you using the right account? (The key must belong to the account that owns the domain)

Sitemap Not Being Indexed

Symptom: Your sitemap is live but Google is not indexing the URLs.

This is usually not a SitemapHost issue, but here are some checks:

1. Submit to GSC -- Add your sitemap URL to Google Search Console
2. Check robots.txt -- Ensure your robots.txt includes the sitemap URL and does not block search engines
3. Verify sitemap content -- Visit the sitemap URL in your browser and confirm URLs are present
4. Connect Google Search Console -- Enable GSC integration for automatic sitemap submission
5. Enable IndexNow -- Check that IndexNow is enabled for faster Bing/Yandex indexing
6. Check GSC for errors -- Google Search Console may report sitemap parsing errors

# Correct robots.txt
User-agent: *
Allow: /

Sitemap: https://sitemap.yoursite.com/sitemap.xml

Getting Help

If you cannot resolve your issue:

1. Check the specific troubleshooting pages: DNS and SSL
2. Review the API Reference for correct endpoint usage
3. Contact support at support@sitemaphost.app with:
   • Your domain name
   • The API response you received
   • Steps to reproduce the issue