Docs · Errors

Referensi kode error.

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

Bentuk response error

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.

Referensi

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.

Blokir guardrail

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.

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

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.

Batas belanja & rate

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.

// 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"
  }
}

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

Resep retry

Exponential backoff dengan jitter

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

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)

Lihat guardrail bekerja pada request nyata.

Dashboard menampilkan setiap blokir beserta prompt yang menyebabkannya.

Buka dashboard Kembali ke docs