Errors and limits

This page describes the error format of the Engy API, the status codes that it returns, and the limits that apply to requests. It is intended for developers who build reliable integrations.

Error formatCopy Anchor Link

On the OpenAI-compatible endpoints, an error response has the following format:

{
  "error": {
    "message": "insufficient credits",
    "type": "insufficient_quota",
    "param": null,
    "code": 402
  }
}

On /v1/messages, errors use the Anthropic format:

{
  "type": "error",
  "error": {"type": "invalid_request_error", "message": "..."}
}

Every response, including an error response, contains the X-Engy-Request-Id header. Include its value when you contact support.

For server errors (status 500 and above), the message is generic and ends with the request ID, for example: service temporarily unavailable; please retry, or report request_id ....

For errors during a streamed response, see Streaming.

Status codesCopy Anchor Link

Context window errorsCopy Anchor Link

A request fails with status 400 if the prompt alone, or the prompt plus max_tokens, exceeds the model's context window. The message states the token counts:

prompt is 300512 tokens, which exceeds the model's context window of 262144; reduce the prompt

On /v1/messages, the message uses the Anthropic wording: prompt is too long: N tokens > M maximum.

To resolve the error, shorten the prompt or reduce max_tokens. For the context window of each model, see Models and pricing.

Capacity and concurrency limitsCopy Anchor Link

The Engy API does not limit requests or tokens per minute, and it does not return rate limit headers. Status 429 indicates one of the following conditions:

Non-streaming 429 responses from /v1/chat/completions, /v1/completions, and /v1/responses include a Retry-After header.

Retry requestsCopy Anchor Link

Retry requests that fail with status 429, 500, 502, 503, or 504. Use exponential backoff with jitter:

import os
import random
import time

import httpx

RETRYABLE = {429, 500, 502, 503, 504}

def create_completion(body, max_attempts=5):
    for attempt in range(max_attempts):
        response = httpx.post(
            "https://api.engy.ai/v1/chat/completions",
            headers={"Authorization": f"Bearer {os.environ['ENGY_API_KEY']}"},
            json=body,
            timeout=600,
        )
        if response.status_code not in RETRYABLE or attempt == max_attempts - 1:
            response.raise_for_status()
            return response.json()

        retry_after = response.headers.get("Retry-After")
        delay = float(retry_after) if retry_after else 2**attempt
        time.sleep(delay + random.uniform(0, 1))

result = create_completion(
    {"model": "glm-5.2", "messages": [{"role": "user", "content": "Hello"}]}
)
print(result["choices"][0]["message"]["content"])

The OpenAI and Anthropic SDKs retry these errors automatically. You can configure the number of retries with the max_retries client option.

If errors persist, check the status page for incidents that affect the service.

Billing for failed requestsCopy Anchor Link

Engy does not charge for a request that fails. This applies to errors from the model server, timeouts, and capacity errors. If you close the connection during a streamed response, Engy stops generation and does not charge for the request.

Request limitsCopy Anchor Link

For non-streaming requests that run longer than 15 seconds, Engy sends whitespace before the response body to keep the connection open. The HTTP status is then 200, and a late error appears in the response body. JSON parsers ignore the leading whitespace. If your requests are long, use streaming or check the body for an error field.