Errors

aicentos follows the OpenAI error response format exactly. When an SDK throws, just catch the corresponding exception.

Error response structureCopy anchor link

Every error response has this shape:

{
  "error": {
    "message": "Your API key does not have access to gpt-5",
    "type": "permission_denied",
    "code": "model_not_allowed",
    "param": "model"
  }
}

HTTP status code referenceCopy anchor link

Common errors and fixesCopy anchor link

401 — Invalid API keyCopy anchor link

{ "error": { "message": "Incorrect API key provided", "type": "authentication_error" } }

Checklist:

• Is the Authorization header in Bearer sk-xxx format (note the space)
• Did copying the key from the console pick up spaces / newlines
• Is the key deleted / disabled / expired
• Did a test key end up in production

402 — Insufficient quotaCopy anchor link

{ "error": { "message": "Insufficient quota", "type": "insufficient_quota" } }

Top up → Wallet Management in the console. Turn on balance alerts to keep it from happening again.

403 — Model not allowedCopy anchor link

{ "error": { "message": "Model gpt-5 not allowed for this key", "code": "model_not_allowed" } }

The token was created with an allowed models allowlist, and the requested model is not on it. Change the token settings or use another key.

404 — Model not foundCopy anchor link

{ "error": { "message": "The model 'gpt-4-turbo-2024-04-09' does not exist", "code": "model_not_found" } }

The model ID is misspelled or has been retired. Check the model marketplace for currently available IDs.

429 — Rate limit exceededCopy anchor link

The Retry-After response header tells you how many seconds to wait before retrying. Lower your concurrency and request rate to recover.

500 / 502 / 503 — Service errorsCopy anchor link

Usually upstream turbulence. Retrying 2-3 times automatically usually succeeds. If it lasts more than 5 minutes:

• Check the status page (if available)
• Contact support

408 / 504 — TimeoutsCopy anchor link

No response after 60 seconds. Common causes:

• The prompt is so long that the model "thinks" past the timeout
• Streaming is not enabled (add stream: true for long responses)

Fixes:

• Shorten the prompt
• Enable streaming: { "model": "...", "messages": [...], "stream": true }
• Switch to a faster model (e.g. from gpt-4o to gpt-4o-mini)

SDK error handling examplesCopy anchor link

export AICENTOS_API_KEY="sk-your-aicentos-api-key"

PythonCopy anchor link

import os
from openai import OpenAI, APIError, RateLimitError, AuthenticationError

client = OpenAI(api_key=os.environ["AICENTOS_API_KEY"], base_url="https://aicentos.com/v1")

try:
    resp = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=[{"role": "user", "content": "hi"}],
    )
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry in {e.response.headers.get('Retry-After')}s")
except APIError as e:
    print(f"Other API error: {e.status_code} {e.message}")

Node.jsCopy anchor link

import OpenAI, { APIError } from 'openai';

const client = new OpenAI({
  apiKey: process.env.AICENTOS_API_KEY,
  baseURL: 'https://aicentos.com/v1',
});

try {
  const resp = await client.chat.completions.create({ ... });
} catch (err) {
  if (err instanceof APIError) {
    console.log(err.status, err.code, err.message);
  }
}

Retry and fallback recommendationsCopy anchor link

The official OpenAI SDKs ship with sensible retry policies by default — use the SDK in production code instead of hand-rolled fetch calls.