Skip to main content
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).

View: Upstream Errors

Characteristics, typical scenarios, and troubleshooting tips for upstream errors.

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

View: System Errors

The fixed response structure and common causes of system errors.

​
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.

View: Unformatted Errors

How to identify path errors, and how to handle non-JSON responses such as timeouts and gateway pages.

​
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:
When you run into a problem and need to contact the team, please provide the Poixe-Request-Id first; this significantly speeds up troubleshooting.