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

# Error Types Overview

The Poixe AI system is an API forwarding and scheduling layer, so errors fall into three broad categories.

Understanding these categories helps you locate problems faster, decide whether to retry, and provide useful information to the team when needed.

## 1. Upstream errors (Upstream)

Upstream errors come from the model provider or its gateway. Common causes include:

* The request body does not conform to the protocol (missing fields, type mismatches, invalid parameters, etc.)
* Authentication failure (invalid Key, insufficient permissions)
* Upstream rate limiting, overload, or service failure

In general, the system tries to catch common upstream errors and decides, based on the error type, whether to retry automatically (for example, brief overload or rate limiting may trigger a retry).

<CardGroup cols={1}>
  <Card title="View: Upstream Errors" icon="list" href="/en/api-reference/introduction/errors/upstream">
    Characteristics, typical scenarios, and troubleshooting tips for upstream errors.
  </Card>
</CardGroup>

## 2. System errors (System)

System errors are generated by the platform itself and are usually related to account status, token status, quotas, and permissions, for example:

* Insufficient account balance
* Token expired / disabled
* Restricted access (insufficient permissions, policy blocks, etc.)

These errors return a **fixed JSON error format**, with the source marked as `system` in `error.source`.

Example:

```json theme={"theme":{"light":"min-light","dark":"min-dark"}}
{
  "error": {
    "message": "Token is expired.",
    "type": "forbidden",
    "source": "system",
    "details": {
      "request_id": "2026010914011404810445",
      "note": "This error was generated by the system, not from any upstream provider."
    }
  }
}
```

<CardGroup cols={1}>
  <Card title="View: System Errors" icon="list" href="/en/api-reference/introduction/errors/system">
    The fixed response structure and common causes of system errors.
  </Card>
</CardGroup>

## 3. Unformatted errors (Unformatted)

Another class of errors occurs on the "client ↔ system" communication path. These errors usually **do not** return well-formed JSON. Common forms include:

* Plain-text errors
* HTML error pages (for example, a CDN timeout page)

A typical example: when a request goes through a CDN and hits the 120-second forced timeout, the client may receive an HTML page instead of JSON.

<CardGroup cols={1}>
  <Card title="View: Unformatted Errors" icon="list" href="/en/api-reference/introduction/errors/unformatted">
    How to identify path errors, and how to handle non-JSON responses such as timeouts and gateway pages.
  </Card>
</CardGroup>

## Non-200 response headers

Whenever the system returns a formatted response body with a status code **other than 200**, the response headers include the following fields:

* `Poixe-Error-Source`: the error source identifier (`system` or `upstream`)
* `Poixe-Request-Id`: the request ID (used for troubleshooting and locating the request)

Example:

```text theme={"theme":{"light":"min-light","dark":"min-dark"}}
Poixe-Error-Source: system
Poixe-Request-Id: 2026010914011404810445
```

When you run into a problem and need to contact the team, please provide the `Poixe-Request-Id` first; this significantly speeds up troubleshooting.


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