Error Handling

Learn how to handle API errors gracefully and troubleshoot common issues.

HTTP Status Codes

Code	Meaning	Action
200	Success	Request completed successfully
400	Bad Request	Check URL encoding and parameters
401	Unauthorized	Check your App ID
403	Forbidden	Target site blocked the request; try proxies
404	Not Found	Target URL doesn't exist
429	Too Many Requests	Rate limited; implement backoff
500	Server Error	Retry the request
502/503	Gateway Error	Target site unavailable; retry later

Error Response Format

Error responses include details about what went wrong:

Error response

{
  "error": true,
  "message": "Invalid App ID",
  "code": "INVALID_APP_ID"
}

MCP Tool Errors

If you're calling OpenGraph.io through the MCP server instead of the REST API, failures aren't surfaced as HTTP status codes — MCP tool calls always return a 200-level response, and errors are signaled inside the result itself:

MCP tool error result

{
  "isError": true,
  "content": [
    {
      "type": "text",
      "text": "## Could not complete request\n\n**Scrape Page** — Target site blocked the request"
    }
  ]
}

Check isError before trusting the result, and read the human-readable reason out of the text content block — there's no separate machine-readable error code or structuredContent on failed calls. The same retry and proxy-escalation parameters used by the REST API (use_proxy, use_premium, use_superior, retry_escalate) are also accepted as MCP tool arguments, so the fixes below apply whether you hit the error via REST or MCP.

Common Errors and Solutions

Invalid App ID (401)

Your App ID is missing or incorrect.

Verify your App ID in the dashboard
Ensure the parameter is named app_id
Check for typos or extra spaces

URL Encoding Issues (400)

The target URL wasn't properly encoded.

Use encodeURIComponent() in JavaScript
Use urllib.parse.quote() with safe='' in Python
See URL Encoding guide

Target Site Blocked (403)

The target website blocked the request.

Try adding use_proxy=true
For Cloudflare sites, try use_premium=true
For heavily protected sites, try use_superior=true
See Proxy Options

Rate Limited (429)

Too many concurrent requests.

Implement exponential backoff
Queue requests to stay within limits
Consider upgrading your plan
See Rate Limits

Target Site Unavailable (502/503)

The target website is down or unresponsive.

Wait and retry the request
Check if the target site is actually online
Try full_render=true for slow sites

Implementing Error Handling

async function fetchOpenGraph(targetUrl) {
  const encodedUrl = encodeURIComponent(targetUrl);
  const apiUrl = `https://opengraph.io/api/3.0/site/${encodedUrl}?app_id=${process.env.APP_ID}`;
  
  const response = await fetch(apiUrl);
  
  if (!response.ok) {
    switch (response.status) {
      case 401:
        throw new Error('Invalid App ID');
      case 403:
        // Retry with proxy
        return fetchWithProxy(targetUrl);
      case 429:
        // Wait and retry
        await sleep(1000);
        return fetchOpenGraph(targetUrl);
      case 404:
        throw new Error('Target URL not found');
      default:
        throw new Error(`API error: ${response.status}`);
    }
  }
  
  return response.json();
}