Error Codes

HTTP Status Codes

Code	Meaning
200	Success
201	Created (POST share)
204	No Content (DELETE)
400	Request validation error
401	Unauthorized
402	Insufficient credits — the account balance is below the task cost (1 credit standard, 5 with triplet_analysis)
403	Forbidden
404	Resource not found
422	Invalid request body format
429	Rate limit exceeded
500	Internal server error

Business Errors (in SSE FAILURE)

These occur inside the state: "FAILURE" event from the status stream.

{
  "state": "FAILURE",
  "error": {
    "code": 1001,
    "message": "The analysis could not be completed."
  }
}

Code	Name	Description
1001	PAGE_UNAVAILABLE	One of the requested pages was not included in the analysis
1002	ANALYSIS_SERVICE_FAILURE	Internal analysis service error
1003	CRITICAL_OWN_PAGE_FAILURE	Your own page returned an error or is unreachable
1004	REPORT_GENERATION_FAILURE	Failed to compile the analysis report
1005	TRIPLET_ANALYSIS_FAILURE	Knowledge Graph extraction failed
9999	UNKNOWN_ERROR	Unexpected error

Handling Errors — Python

with requests.get(stream_url, headers=HEADERS, stream=True) as resp:
    for line in resp.iter_lines():
        if not line or not line.startswith(b"data: "):
            continue
        event = json.loads(line[6:])
        if event["state"] == "FAILURE":
            err = event.get("error", {})
            raise RuntimeError(f"[{err.get('code')}] {err.get('message')}")

Validation Errors (422)

{
  "detail": [
    {
      "loc": ["body", "competitor_urls"],
      "msg": "ensure this value has at most 20 items",
      "type": "value_error.list.max_items"
    }
  ]
}