Errors & limits — uncens.ai API

error format

400 · application/json

{
  "error": {
    "message": "Parameter \"top_k\" is not supported by model \"uncens-pro\". Use temperature, top_p, frequency_penalty and presence_penalty to control sampling.",
    "type": "invalid_request_error",
    "code": "unsupported_parameter",
    "param": "top_k",
    "request_id": "420361d4-08c4-4db4-b3b7-1fe27ec18859"
  }
}

param is the offending field or null. type is invalid_request_error, or authentication_error on 401. request_id is also returned in the X-Request-Id response header on every call, including successful ones.

codes

http	code	when	what to do
400	invalid_request_error	A field is missing, has the wrong type or is out of range.	Fix the request. Do not retry.
400	unsupported_parameter	`top_k`, `min_p` or `repetition_penalty` was sent.	Drop the field named in `param`.
400	invalid_json	The body is not valid JSON.	Fix serialization.
400	request_too_large	The body exceeds the accepted size.	Trim history or split the request.
401	missing_api_key	No `Authorization` header, or it is not a bearer token.	Send `Authorization: Bearer sk-uncens-...`
401	invalid_api_key	Unknown or malformed key.	Check the key. Do not retry.
401	access_key_disabled	The key exists but has been switched off.	Get a new key.
404	model_not_found	`model` is not `uncens-pro` or `uncens-mini`.	Use a listed model id.
404	unknown_endpoint	The path does not exist, e.g. `/v1/embeddings`.	Only chat completions and models are served.
429	quota_exceeded	The key ran out of tokens.	Top up. Retrying will not help.
429	rate_limit_exceeded	More than 60 requests in a minute.	Wait `Retry-After` seconds, then retry.
500	internal_error	Unexpected failure on our side.	Retry with backoff.
503	service_unavailable	The backend is not reachable right now.	Retry with backoff.
503	no_capacity	No free capacity to start generation.	Retry with backoff.
503	service_error	The backend answered with an error.	Retry with backoff.
—	stream_interrupted	A stream died mid-flight; arrives as an error event inside the SSE body.	Retry the whole request.
—	request_aborted	The client closed the connection before the answer finished.	Nothing — tokens already produced are still counted.

quota & rate limit

Each key has a token quota. Input and output both count against it (usage.total_tokens). When it runs out, every call returns 429 quota_exceeded. Request rate is capped separately at 60 requests per minute; over that you get 429 rate_limit_exceeded with a Retry-After header.

response headers

X-Tokens-Limit:                 1000000
X-Tokens-Used:                  135
X-Tokens-Remaining:             999865
X-RateLimit-Limit-Requests:     60
X-RateLimit-Remaining-Requests: 58

The model is stateless: every request resends the whole conversation, so prompt_tokens covers the full history, not just the newest message. A long chat therefore burns quota faster with each turn — trim or summarize old messages. reasoning_effort above none adds output tokens on top of that.

retries

retry429 rate_limit_exceeded, 500, 503, stream_interrupted
don't400, 401, 404, 429 quota_exceeded — the same request will fail again

python

import random, time
import httpx

URL = "https://uncens.ai/v1/chat/completions"
HEADERS = {"Authorization": "Bearer sk-uncens-..."}
RETRY = {429, 500, 503}


def complete(body, attempts=5):
    for i in range(attempts):
        r = httpx.post(URL, headers=HEADERS, json=body, timeout=120)
        if r.status_code < 400:
            return r.json()

        code = r.json().get("error", {}).get("code")
        # out of tokens — retrying cannot help
        if r.status_code not in RETRY or code == "quota_exceeded":
            r.raise_for_status()

        # honour Retry-After, otherwise exponential backoff + jitter
        wait = float(r.headers.get("Retry-After", 0)) or 2 ** i
        time.sleep(wait + random.random())

    raise RuntimeError("still failing after retries")