Troubleshooting Guide

Common Issues and Solutions

Price Anomalies

Symptom: Prices appear 10x or 100x off expected values

Common Cause: Decimal point parsing error or unit confusion

Solution:

  1. Check the currency and unit fields in the API response
  2. For UK Natural Gas: Values are in pence (GBp), not pounds
  3. Verify against our expected ranges:
    • UK Natural Gas: 30-200 pence/therm
    • Brent/WTI: $20-$200/barrel
    • Gold: $1,500-$3,000/oz

Prevention: Always validate units before processing prices

Symptom: Historical data shows inconsistent values

Common Cause: Data correction in progress or recently completed

Solution:

  1. Check for recent incident notifications
  2. Use the /v1/commodities/{code}/status endpoint for data quality info
  3. Re-fetch historical data after corrections complete

Prevention: Subscribe to webhook notifications for data corrections

Symptom: Sudden price spikes or drops

Common Cause: Market volatility or feed issues

Solution:

  1. Compare with multiple time periods (3-min, hourly, daily averages)
  2. Check our status page for feed disruptions
  3. Verify against external sources for major market events

Prevention: Implement sanity checks in your application

API Access Issues

Symptom: 403 Forbidden on premium endpoints

Common Cause: Insufficient subscription tier

Solution:

  1. Check your current plan at dashboard.oilpriceapi.com
  2. Verify endpoint access requirements in documentation
  3. Upgrade plan if needed for premium features

Endpoint Access by Tier:

  • Free/Hobby: Basic spot prices, limited history
  • Starter: Extended history, more frequent updates
  • Professional: Weather data, pipeline flows, WebSocket
  • Business/Enterprise: All features, priority support

Symptom: 429 Rate Limit Exceeded

Common Cause: Too many requests in time window

Solution:

  1. Check response headers for rate limit info:
    • X-RateLimit-Limit: Your limit
    • X-RateLimit-Remaining: Requests left
    • X-RateLimit-Reset: Reset timestamp
  2. Implement exponential backoff
  3. Cache responses appropriately

Rate Limits by Tier:

  • Free: 1,000/month
  • Hobby: 10,000/month
  • Starter: 50,000/month
  • Professional: 100,000/month
  • Business: 200,000/month

Symptom: Authentication failures

Common Cause: Invalid or expired API key

Solution:

  1. Verify API key in request headers: Authorization: Token YOUR_API_KEY
  2. Check key status in dashboard
  3. Regenerate key if compromised
  4. Ensure no extra spaces or characters
  5. Use Token prefix, not Bearer

Data Feed Issues

Symptom: Missing data for specific time periods

Common Cause: Feed disruption or maintenance

Solution:

  1. Check our status page for maintenance windows
  2. Use fallback to last known good value
  3. Wait for backfill (usually within 15 minutes)

Affected Feeds & Recovery:

  • EIA Storage: Weekly updates Thursdays 10:30 AM ET
  • Weather Data: Daily updates, 6-hour recovery window
  • Exchange Prices: 15-minute recovery for disruptions

Symptom: WebSocket connection drops frequently

Common Cause: Network issues or subscription limits

Solution:

  1. Implement automatic reconnection with backoff
  2. Check subscription includes WebSocket access
  3. Monitor for rate limiting on connections
  4. Use connection pooling for multiple streams

WebSocket Best Practices:

// Automatic reconnection example
let reconnectDelay = 1000;
const maxDelay = 30000;

function connect() {
  const ws = new WebSocket('wss://api.oilpriceapi.com/v1/stream');
  
  ws.onclose = () => {
    setTimeout(() => {
      reconnectDelay = Math.min(reconnectDelay * 2, maxDelay);
      connect();
    }, reconnectDelay);
  };
  
  ws.onopen = () => {
    reconnectDelay = 1000; // Reset delay on successful connection
  };
}

Historical Data Issues

Symptom: Gaps in historical price data

Common Cause: Market closures or feed availability

Solution:

  1. Check market hours for the commodity
  2. Account for weekends and holidays
  3. Use interpolation for minor gaps
  4. Contact support for extended outages

Market Hours:

  • Oil/Gas: 24/5 (closed weekends)
  • Precious Metals: 24/5 with reduced weekend liquidity
  • UK Natural Gas: UK trading hours (8 AM - 6 PM GMT)

Symptom: Different values for same timestamp

Common Cause: Multiple data sources or corrections applied

Solution:

  1. Use the most recent API response
  2. Check last_updated field for data freshness
  3. Prefer corrected data (check incident notifications)

Integration Issues

Symptom: Prices don't match website display

Common Cause: Different update frequencies or caching

Solution:

  1. Check update frequency for your tier
  2. Account for display rounding (website may show fewer decimals)
  3. Verify timezone handling (all times in UTC)
  4. Clear any client-side caches

Symptom: Webhook events not received

Common Cause: Endpoint configuration or network issues

Solution:

  1. Verify endpoint URL is publicly accessible
  2. Check webhook signature validation
  3. Ensure endpoint responds with 200 status
  4. Review webhook logs in dashboard

Webhook Debugging:

# Test your endpoint
curl -X POST https://your-endpoint.com/webhook \
  -H "Content-Type: application/json" \
  -H "X-OilPriceAPI-Signature: test" \
  -d '{"event":"price.updated","commodity":"BRENT","price":85.50}'

Debugging Checklist

For Price Issues

  • [ ] Verify currency and unit fields
  • [ ] Check against expected ranges
  • [ ] Compare multiple time periods
  • [ ] Review recent corrections
  • [ ] Validate timezone handling

For API Issues

  • [ ] Confirm API key is valid
  • [ ] Check rate limit headers
  • [ ] Verify subscription tier
  • [ ] Test with curl command
  • [ ] Review error message details

For Data Quality

  • [ ] Check status page
  • [ ] Review incident notifications
  • [ ] Compare with backup sources
  • [ ] Contact support if persistent

Getting Help

Self-Service Resources

  • Documentation: docs.oilpriceapi.com
  • Status Page: status.oilpriceapi.com
  • Dashboard: dashboard.oilpriceapi.com
  • API Explorer: api.oilpriceapi.com/explorer

Contact Support

  • Email: [email protected]
  • Response Time:
    • Critical: 3 business days
    • Major: 3 business days
    • Minor: 3 business days
  • Include in Report:
    • API key (first 8 characters only)
    • Exact timestamp of issue
    • Commodity code affected
    • Expected vs actual values
    • Error messages received

Emergency Contacts

For critical production issues affecting trading:

  • Hotline: Available for Enterprise customers
  • Escalation: Via account manager
  • SLA: Based on subscription tier