Error Codes

HTTP Status Codes

Code	Meaning
200	Success
201	Created (POST share)
204	No Content (DELETE)
400	Request validation error
401	Unauthorized
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": "Failed to parse page: connection timeout"
  }
}

Code	Name	Description
1001	PARSER_FAILURE	A page URL could not be fetched or parsed
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"
    }
  ]
}