> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octen.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes

> What each error code means and how to fix it.

<p style={{ fontSize: "0.8rem", opacity: 0.6 }}>For AI agents: <a href="https://docs.octen.ai/resources/error-codes.md">docs.octen.ai/resources/error-codes.md</a></p>

## 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:

```json theme={null}
{
  "code": 400,
  "msg": "Invalid params. Missing parameter query",
  "request_id": "20260818123456ABCDEFGHIJ"
}
```

### Response Fields

| Field | Type | Description |
| - | - | - |
| `code` | integer | HTTP status code indicating the error type |
| `msg` | string | Human-readable message describing the error |
| `request_id` | string | Unique identifier for the request |

Model Gateway endpoints (`/v1/chat/completions`, `/v1/messages`, `/v1/images/generations`) return errors in the native OpenAI or Anthropic format, which does not include `request_id` in the body. For those, read the `x-request-id` response header, which every endpoint returns on error.

## 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:

```json theme={null}
{
  "code": 0,
  "msg": "success",
  "data": {
    "results": [
      { "url": "https://example.com/ok", "status": "success", "resolved_mode": "standard" },
      {
        "url": "https://example.com/missing",
        "status": "failed",
        "error_message": "Target returned HTTP 404"
      }
    ]
  },
  "meta": {
    "usage": {
      "total_urls": 2,
      "successful_urls": 1,
      "successful_by_mode": { "standard_urls": 1, "advanced_urls": 0 }
    }
  }
}
```

Common `error_message` values returned by Extract:

| Scenario | message |
| - | - |
| Invalid URL format, including URLs longer than 2,048 characters | `Invalid URL format` |
| Scanned or image-only PDF | `PDF has no extractable text (likely scanned)` |
| 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](mailto:support@octen.ai) with your `request_id`

***

<p style={{ fontSize: "0.8rem", opacity: 0.6 }}>Last modified on August 21, 2026</p>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.