Setiap HTTP status dan error.code yang dikembalikan gateway, apa penyebabnya, dan bagaimana client Anda harus menanganinya.

Body error standar

Setiap response error dari Anoman adalah satu objek JSON dengan sebuah key error. Bentuknya cocok dengan envelope error OpenAI sehingga penanganan error SDK yang ada bekerja tanpa perubahan.

{
  "error": {
    "type": "invalid_request_error" | "guardrail_error" | "rate_limit_error" | "provider_error" | "billing_error",
    "code": "machine_readable_code",
    "message": "Human-readable explanation",
    "param": "messages.0.content"   // (optional) which field caused the error
  }
}

Field type mengelompokkan error ke dalam lima famili; code adalah string spesifik yang dapat dibaca mesin yang harus Anda switch di kode client.

Semua kode error

Kode dikelompokkan berdasarkan famili. Kolom Retry memberi tahu apakah retry-with-backoff adalah respons yang tepat.

HTTP	Kode	Tipe	Penyebab	Retry?
401	`auth_missing`	invalid_request	Tidak ada header Authorization	Tidak
401	`auth_invalid`	invalid_request	Key rusak atau tidak dikenal	Tidak
403	`auth_revoked`	invalid_request	Key dicabut	Tidak
402	`budget_exceeded`	billing	Cap USD bulanan per key tercapai	Tidak
402	`insufficient_credits`	billing	Saldo prabayar habis	Tidak
402	`token_quota_exceeded`	billing	Token cap mingguan atau bulanan tercapai untuk sebuah model tier class	Tidak
403	`prompt_injection`	guardrail	Classifier injeksi menandai konten pengguna	Tidak
403	`pii_blocked`	guardrail	PII terdeteksi dan mode policy adalah `block`	Tidak
403	`content_violation`	guardrail	Moderasi konten memblokir request	Tidak
403	`tool_denied`	guardrail	Nama tool muncul di denylist policy	Tidak
403	`tool_not_allowed`	guardrail	Tool tidak ada di allowlist policy	Tidak
400	`model_not_found`	invalid_request	Slug model tidak ada di katalog kami	Tidak
400	`context_length_exceeded`	invalid_request	Prompt + completion melebihi context window model	Tidak
400	`vision_not_supported`	invalid_request	Input gambar dikirim ke model teks-saja	Tidak
429	`rate_limit_exceeded`	rate_limit	Burst guard RPM atau TPM terpicu	Ya
429	`concurrent_limit_exceeded`	rate_limit	Inflight cap tercapai untuk key ini	Ya
503	`provider_unavailable`	provider	Semua route upstream gagal setelah retry	Ya
504	`provider_timeout`	provider	Upstream tidak merespons dalam 120s	Ya
503	`cost_cap_open`	provider	Circuit breaker terbuka pada upstream	Ya

Error auth + budget + guardrail langsung dikembalikan dan tidak akan berhasil saat retry — perbaiki request atau konfigurasinya. Error rate limit + provider bersifat transien — retry dengan exponential backoff dan hormati header Retry-After.

Membaca error guardrail 403

Ketika guardrail memblokir sebuah request, response-nya adalah 403 dan type adalah guardrail_error. Rincian pass/fail guardrail lengkap juga diekspos pada response yang berhasil di objek _anoman.guardrails, lihat Guardrails.

403 — prompt injection diblokir

{
  "error": {
    "type": "guardrail_error",
    "code": "prompt_injection",
    "message": "Request blocked by prompt injection detector (score 0.94 > threshold 0.85)."
  }
}

403 — tool ditolak oleh policy

{
  "error": {
    "type": "guardrail_error",
    "code": "tool_denied",
    "message": "Tool 'delete_file' is denied by policy group 'production'.",
    "param": "tools.0"
  }
}

Blokir guardrail adalah perilaku yang benar — jangan retry secara diam-diam. Entah tampilkan ke end user (dengan pesan penolakan generik) atau eskalasikan ke antrean review manusia jika permukaannya berisiko tinggi.

Membaca response 402 dan 429

Jangan mengacaukan batas belanja dengan flood guard. 402 token_quota_exceeded berarti Anda mencapai token cap mingguan atau bulanan sebuah model tier class — tidak dapat di-retry sampai jendela bergulir (beli token pack, upgrade, atau ganti model class). 429 rate_limit_exceeded berarti sebuah burst guard RPM/TPM terisi penuh, dan concurrent_limit_exceeded berarti terlalu banyak request inflight bersamaan — keduanya transien, aman untuk di-retry dengan backoff.

402 — kuota token terlampaui (model tier class)

// HTTP 402 Payment Required — the spend boundary on flat tiers.
 
{
  "error": {
    "type": "billing_error",
    "code": "token_quota_exceeded",
    "message": "Monthly token cap reached for the 'premium' model tier class.",
    "model_tier_class": "premium",
    "window": "monthly"
  }
}

429 — burst guard RPM terpicu

// Response headers also include:
//   x-anoman-rate-limit-rpm:     120
//   x-anoman-rate-remaining-rpm: 0
//   retry-after: 24
 
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "120 RPM limit exceeded. Retry after 24s."
  }
}

429 — inflight cap (request bersamaan)

// Response headers:
//   x-anoman-inflight-cap: 150
//   x-anoman-inflight-current: 150
//   x-anoman-tier: pro
 
{
  "error": {
    "type": "rate_limit_error",
    "code": "concurrent_limit_exceeded",
    "message": "Per-key inflight cap (150) reached. Drop concurrency or upgrade tier."
  }
}

Referensi limit per-tier + header lengkap di Rate limits.

Exponential backoff dengan jitter

SDK OpenAI / Anthropic sudah retry secara default, tetapi default-nya konservatif. Berikut pola eksplisit yang menghormati Retry-After:

Python — retry tangguh dengan exponential backoff

import time
import random
from openai import OpenAI
from openai import APIStatusError
 
client = OpenAI(base_url="https://api.anoman.io/v1", api_key="anm-sk-...")
 
def chat_with_retry(messages, model="gpt-4o-mini", max_attempts=5):
    for attempt in range(max_attempts):
        try:
            return client.chat.completions.create(model=model, messages=messages)
        except APIStatusError as e:
            # Retry on 429 (rate limit), 503 (provider unavailable),
            # 504 (gateway timeout). Bail on 4xx auth/budget errors.
            if e.status_code not in {429, 503, 504}:
                raise
            if attempt == max_attempts - 1:
                raise
            # Respect Retry-After header when present.
            retry_after = float(e.response.headers.get("retry-after", 0))
            sleep = retry_after or min(2 ** attempt + random.random(), 30)
            time.sleep(sleep)

TypeScript — retry tangguh

import OpenAI, { APIError } from "openai";
 
const client = new OpenAI({
  baseURL: "https://api.anoman.io/v1",
  apiKey: process.env.ANOMAN_API_KEY,
});
 
async function chatWithRetry<T>(
  fn: () => Promise<T>,
  maxAttempts = 5,
): Promise<T> {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (!(err instanceof APIError)) throw err;
      // Only retry rate limit + transient upstream errors.
      if (![429, 503, 504].includes(err.status ?? 0)) throw err;
      if (attempt === maxAttempts - 1) throw err;
      const retryAfter = Number(err.headers?.["retry-after"] ?? 0);
      const sleep = retryAfter || Math.min(2 ** attempt + Math.random(), 30);
      await new Promise(r => setTimeout(r, sleep * 1000));
    }
  }
  throw new Error("unreachable");
}

Lihat guardrail bekerja pada request nyata.

Dashboard menampilkan setiap blokir beserta prompt yang menyebabkannya.

Referensi kode error.