Resolving authentication failures, rate limits, and payload validation errors.
401 Unauthorized / Invalid API Key
This occurs when the API key is expired, mismatched, or lacks scope permissions.
- Verify your key in
Dashboard → Settings → API Keys
- Ensure you're using the
live key, not test
- Regenerate if compromised:
client.regenerateKey('sitemap_writer')
⚠️ Keys are region-specific. US keys won't work on EU endpoints.
429 Too Many Requests (Rate Limiting)
Sitemap.xml applies dynamic rate limits based on plan tier. Default is 60 req/min for Pro.
- Implement exponential backoff in your client
- Check
X-RateLimit-Remaining header in responses
- Use bulk endpoints
/v2/bulk/urls for large payloads
const response = await client.submit(
urls, { retry: true, maxRetries: 3 }
);
Pages submitted but not appearing in search results within expected SLA.
URL stuck in "Submitted, not indexed" state
Common causes include server response codes, canonical conflicts, or JS rendering issues.
- Verify server returns
200 OK for the URL
- Check for
noindex meta tags or X-Robots-Tag: noindex
- Ensure canonical tags point to the preferred version
- Run a render check:
curl -I https://yoursite.com/page
💡 Sitemap.xml automatically flags render-blocking resources. Check your coverage report.
Google/Bing sync shows "Sitemap could not be fetched"
This indicates a 404 or permission error when search engines request your sitemap endpoint.
- Confirm
/sitemap.xml is publicly accessible
- Disable IP whitelisting for sitemap paths
- Verify DNS propagation if recently migrated
- Use our diagnostic tool:
sitemap.xml/verify?url=...
Fixing sync failures for WordPress, Shopify, Webflow, and headless setups.
WordPress plugin not detecting new posts
The plugin relies on WordPress hooks. If custom post types aren't appearing, registration may be misconfigured.
- Ensure
'public' => true and 'show_in_rest' => true are set
- Flush permalinks:
Settings → Permalinks → Save
- Check plugin logs:
WP_DEBUG_LOG for hook conflicts
Shopify Liquid template overrides breaking XML output
Custom theme edits may accidentally wrap the sitemap template in <html> tags.
- Revert
sitemap.xml.liquid to default if manually edited
- Use our app-managed template: enable
Auto-Template in app settings
- Validate output against W3C XML schema
Account access, dashboard rendering, and project configuration help.
Dashboard shows "Project paused" or "Billing overdue"
Projects pause automatically after 3 days of failed payment to prevent index bloat.
- Update payment method:
Billing → Update Card
- Contact billing@sitemap.xml if charged incorrectly
- Reactivate manually after payment processes (up to 15 min)
XML output contains malformed tags or encoding errors
Usually caused by special characters in URLs or metadata not properly escaped.
- Enable
Strict UTF-8 Validation in generator settings
- Replace unescaped ampersands (
&) in query strings
- Run local validation:
xmlint --noout sitemap.xml
Fixing webhook delivery failures and session timeouts.
Webhooks returning 403 or failing verification
Sitemap.xml signs payloads using HMAC-SHA256. Verification must match.
const sig = crypto.createHmac('sha256', secret)
.update(rawBody).digest('hex');
if (sig !== req.headers['x-sitemap-signature']) return res.status(403).end();
- Ensure you're comparing raw body, not parsed JSON
- Webhook endpoints must respond within 3s
- Check retry policy in
Dashboard → Webhooks → Logs