Errors
Stable error codes
Extraction failures include errorCode and errorMessage. Agents should branch on the code, not the human string.
| Code | Meaning | What to do |
|---|---|---|
INVALID_URL | URL missing, malformed, or not a post | Ask the user for a full public post URL |
PLATFORM_NOT_SUPPORTED | Host not in the catalog | Check /docs/platforms or /features |
PRIVATE_OR_UNAVAILABLE | Private, geo-blocked, or deleted | Do not retry blindly; tell the user |
RATE_LIMIT | Provider or app rate limit | Wait; honor Retry-After if present |
EXTRACTION_FAILED | Provider cascade exhausted | Retry once; then report partial results |
API_ERROR | Internal or upstream API error | Retry with backoff |
HTTP 401: missing/invalid JWT. HTTP 402-equivalent: insufficient credits (message in body). HTTP 429: rate limited.