Octen Docs | The Search infrastructure for AI

For AI agents: docs.octen.ai/resources/error-codes.md

API Errors

Code	Message	Cause	Solution
400	Bad Request	Missing required parameter or invalid request format	Verify all required parameters are included and properly formatted
401	Unauthorized	Invalid or missing API key	Ensure your API key is correct and included in request headers
403	Forbidden	Insufficient account balance	Check your account balance and add credits if needed
413	Request Entity Too Large	Request payload exceeds the allowed size limit	Reduce payload size (e.g., shorten input or split into smaller requests)
429	Too Many Requests	Request rate limit exceeded	Implement exponential backoff and reduce request rate
500	Internal Server Error	Unexpected server-side error occurred	Retry your request after a brief delay. Contact support if issue persists

Error Response Structure

All error responses follow a consistent structure:

{
  "code": 400,
  "msg": "Missing parameter query",
  "data": {},
  "meta": {}
}

Response Fields

Field	Type	Description
`code`	integer	HTTP status code indicating the error type
`msg`	string	Human-readable message describing the error
`data`	object	Additional error details (typically empty for errors)
`meta`	object	Metadata about the error (typically empty for errors)

Extract: Partial Failures

A request to Extract may return 200 OK overall while individual URLs within the request fail; failed URLs are marked with status: "failed" and include an error_message. Failed URLs are not billed. This per-URL success/failure model is currently unique to the Extract API. Example response with partial failures:

{
  "code": 0,
  "msg": "success",
  "data": {
    "results": [
      { "url": "https://example.com/ok", "status": "success" },
      {
        "url": "https://example.com/missing",
        "status": "failed",
        "error_message": "Target returned HTTP 404"
      }
    ]
  },
  "meta": {
    "usage": { "total_urls": 2, "successful_urls": 1 }
  }
}

Common error_message values returned by Extract:

Scenario	message
Invalid URL format	`Invalid URL format`
DNS resolution failed	`Failed to resolve domain`
Target host unreachable	`Target host unreachable`
Target returned 4xx	`Target returned HTTP {code}`
Target returned 5xx	`Target server error (HTTP {code})`
Anti-bot protection blocked the request	`Blocked by target anti-bot protection`
Target rate-limited the request	`Target rate limited (HTTP 429)`
Extraction timeout exceeded	`Extraction timed out after {timeout}s`
JavaScript rendering failed	`Page requires JavaScript rendering but failed`
Unsupported content type	`Content type not supported: {content_type}`
HTML parsing failed	`Failed to parse page content`

Getting Help

If you encounter persistent errors or need clarification:

API Reference: Check our API Documentation for parameter requirements
Rate Limits: Review the Rate Limits page for your plan
Status Page: Visit status for real-time system status
Contact Support: Email support@octen.ai with your request_id

​API Errors

​Error Response Structure

​Response Fields

​Extract: Partial Failures

​Getting Help

API Errors

Error Response Structure

Response Fields

Extract: Partial Failures

Getting Help