API Error Recovery

Use this guide when a request fails in development or production. Start with the HTTP status, not a presumed JSON shape: error bodies differ by endpoint and an unknown-route 404 can have an empty HTML body. The complete response-shape reference is Error Codes.

Why did I get this error?

402 and 429 are intentionally different. A quota reset is a billing-cycle event; a rate limit clears as the rolling request window drains. See Rate Limiting for headers, quotas, and a backoff example.

Capture details safely

Before contacting support, capture this information. Redact the API key, Authorization header, cookie values, webhook signing secret, and full request body if it may contain customer data.

time_utc: 2026-07-19T16:30:00Z
endpoint: GET /v1/ei/well-permits
status: 403
request_id: <response request ID, if supplied>
account_plan: scale
required_plan_or_feature: Energy Intelligence / well_permits_data
remediation_url: https://docs.oilpriceapi.com/guides/error-recovery

/v1/account supplies the plan, subscription status, and canonical monthly quota for the key used by the failing client:

curl "https://api.oilpriceapi.com/v1/account" \
  -H "Authorization: Token $OILPRICE_API_KEY"

# Print only non-secret account state for an incident record.
curl -sS "https://api.oilpriceapi.com/v1/account" \
  -H "Authorization: Token $OILPRICE_API_KEY" |
  jq '{plan: .data.plan, subscription_status: .data.subscription_status, quota: .data.quota}'

Never paste a key into a ticket, browser console, issue, or log. If a key may have been exposed, roll or revoke it from the dashboard before investigating further.

Feature and plan gates

All clients use the same API hostname and authentication header. Access is attached to the account behind the key, so changing a plan does not require a new integration.

For a locked Scale endpoint, a non-entitled key should be handled as a non-retryable access failure:

curl -i "https://api.oilpriceapi.com/v1/ei/well-permits?per_page=1" \
  -H "Authorization: Token $OILPRICE_API_KEY"

{
  "error": {
    "code": "INSUFFICIENT_PLAN",
    "message": "This endpoint requires a higher-tier subscription.",
    "required_tier": "scale"
  }
}

The response envelope can vary by endpoint. Treat the HTTP 403 as the stable contract, display a useful next action, and preserve any returned request ID.

Build clients that recover cleanly

Keep ordinary API keys out of browsers

Do not put an OilPriceAPI key in browser JavaScript, a mobile app bundle, or a public static site. Put the key in server-side configuration and expose a purpose-built endpoint from your application instead:

// Server-side route. The browser calls /api/market-price, never OilPriceAPI
// directly with a credential.
app.get('/api/market-price', async (_request, response) => {
  const upstream = await fetch(
    'https://api.oilpriceapi.com/v1/prices/latest?by_code=WTI_USD',
    { headers: { Authorization: `Token ${process.env.OILPRICE_API_KEY}` } },
  );

  response.status(upstream.status).json(await upstream.json());
});

Apply authentication, input validation, cache policy, and response filtering to that application endpoint. More deployment guidance is in the Security Guide.

Match the response shape to the request

The single-price and multi-price endpoints are not interchangeable:

• A request for one price should handle the single-price response documented on its endpoint.
• Batch, all-price, and demo requests return collections; iterate the returned list rather than reading a singular price field.
• Keep the original endpoint and query parameters in logs, because they explain which shape your parser expected.

For a no-key smoke test, keep GET /v1/demo/prices in CI and local setup. It uses real response fields without consuming an authenticated quota; it is not a substitute for entitled production data.

Status and data limitations

Use the human-readable status page to assess an incident and GET https://api.oilpriceapi.com/v1/status for machine checks. Do not use the website status page as a JSON health-check endpoint.

Energy Intelligence products have source-specific boundaries:

• Well Permits has state-portal schedules and source-dependent freshness.
• Well Production beta has limited coverage and may return incomplete or empty results.
• FracFocus and DUC Wells should be interpreted with their source and update notes, not as universal real-time feeds.

See Data Quality and Data Freshness when an otherwise successful response looks stale or incomplete.

Canonical links

• Documentation: https://docs.oilpriceapi.com/...
• Interactive API Explorer: https://docs.oilpriceapi.com/api-reference/interactive
• API base URL: https://api.oilpriceapi.com/v1