Skip to main content
On error, OpenPAI returns a standard HTTP status code plus a JSON error body. The error structure is fully compatible with OpenAI’s, so it plugs seamlessly into existing SDK error handling.

​
Error response structure

{
  "error": {
    "message": "Incorrect API key provided.",
    "type": "invalid_request_error",
    "param": null,
    "code": "invalid_api_key"
  }
}
FieldMeaning
messageA human-readable error description, fine to show to developers
typeError category: invalid_request_error / authentication_error / billing_error / rate_limit_error / server_error
paramThe name of the offending field (if applicable)
codeA machine-recognizable error code

​
Common error codes

​
400 invalid_request

codeMeaning
invalid_request_errorMalformed request body / missing required field
invalid_modelModel ID doesn’t exist or isn’t in the token allowlist
context_length_exceededInput + output tokens exceed the model’s context window
unsupported_modalityThe model doesn’t support image / audio / video input

​
401 authentication

codeMeaning
invalid_api_keyAPI key doesn’t exist / deleted / wrong format
expired_api_keyThe token has expired
disabled_api_keyThe token has been disabled

​
403 forbidden

codeMeaning
insufficient_quotaAccount or token quota exhausted
ip_not_allowedThe source IP isn’t in the allowlist
model_not_allowedThe token lacks permission for this model

​
404 not_found

codeMeaning
model_not_foundThe model doesn’t exist (retired / misspelled)
resource_not_foundThe resource (task, file) doesn’t exist

​
429 rate_limit

codeMeaning
rate_limit_exceededRPM / TPM rate limit hit
concurrent_limit_exceededConcurrency exceeds the group ceiling
upstream_rate_limitedThe upstream vendor returned a 429
The 429 response includes a Retry-After header (seconds); use exponential-backoff retries.

​
5xx server_error

codeMeaning
server_errorInternal gateway error, usually auto-retried
upstream_unavailableAll upstream channels are unavailable
upstream_timeoutUpstream timed out
bad_gatewayThe upstream returned an invalid response
5xx errors are not billed (if the upstream already generated tokens, they’re settled by actual usage).

​
Errors during streaming

If a streaming response errors midway, it sends an error event as SSE and then closes the connection: 
data: {"error":{"message":"Upstream timeout","type":"server_error","code":"upstream_timeout"}}

data: [DONE]
The client should watch for the error field in the SSE data, not just the HTTP status code.

​
Retry guidance

from openai import OpenAI
import time

client = OpenAI(api_key="sk-...", base_url="https://openp.ai/v1")

def call_with_retry(**kwargs):
    delay = 1
    for attempt in range(5):
        try:
            return client.chat.completions.create(**kwargs)
        except openai.RateLimitError:
            time.sleep(delay)
            delay = min(delay * 2, 30)
        except openai.APIError as e:
            if e.status_code >= 500:
                time.sleep(delay)
                delay = min(delay * 2, 30)
            else:
                raise
    raise RuntimeError("max retries exceeded")

​
Reporting issues

When you get an error you can’t make sense of:
  1. Copy the X-OpenPAI-Request-Id from the response headers.
  2. Search for that ID in Console → Logs to see metadata like the model, token usage and error code.
  3. If you still can’t pin it down, record the Request ID and reproduction steps for later investigation.