Xəta kodları
Bütün xətalar eyni formadadır:
{"error": "rate_limited", "message": "Dəqiqəlik limit aşıldı. Bir az sonra yenidən cəhd edin."}
error — proqram üçün sabit kod; message — insan üçün Azərbaycanca izah.
| HTTP | error |
Səbəb | Nə etməli |
|---|---|---|---|
| 401 | unauthorized |
X-API-Key (və ya /mcp-də OAuth tokeni) yoxdur, ya da açar tanınmır |
Başlığı yoxlayın; açar hq_ ilə başlayır |
| 401 | invalid_token |
/mcp: OAuth tokeni tanınmır, vaxtı keçib və ya qoşulma ləğv edilib/bitib |
Klient tokeni yeniləyir və ya yenidən «Connect» istəyir |
| 401 | key_revoked |
Açar ləğv edilib | Kabinetdə yeni açar yaradın |
| 401 | key_expired |
Açarın müddəti bitib (müddətli planlarda) | Kabinetdə açarın yanındakı «Yenilə» düyməsini basın |
| 403 | forbidden |
Endpoint sizin plan üçün bağlıdır | Planı yüksəldin (Limitlər) |
| 404 | not_found |
Maddə yoxdur və ya id formatı səhvdir | article_id-ni search nəticəsindən götürün |
| 422 | validation_error |
Sorğu parametrləri düzgün deyil | message-dəki sahəni düzəldin |
| 429 | rate_limited |
Hesabın dəqiqəlik limiti (bütün açarlar üçün ortaq) | Retry-After saniyə gözləyin |
| 429 | ip_rate_limited |
Bir IP-dən dəqiqəlik tavan | Retry-After saniyə gözləyin |
| 429 | quota_exceeded |
Hesabın aylıq kvotası bitib | Növbəti ayı gözləyin və ya planı yüksəldin |
| 503 | upstream_unavailable |
Qanun bazası cavab vermir | 30 s sonra təkrar; sorğu kvotadan düşmür |
MCP-də eyni kodlar alətin xəta mətnində kod: mesaj şəklində qayıdır (isError: true).
MCP və OAuth
Kimlik məlumatı olmayan /mcp sorğusu 401 qaytarır. Cavabda bu başlıq olur:
WWW-Authenticate: Bearer resource_metadata="https://api.huqsi.az/.well-known/oauth-protected-resource/mcp", scope="read".
Claude.ai, ChatGPT və digər klientlərdə OAuth girişi bu cavabla başlayır. OAuth endpoint-ləri (/oauth/token,
/oauth/register …) standart OAuth xəta kodlarını qaytarır (invalid_grant, invalid_client_metadata …).
Refresh zamanı invalid_grant gəlirsə, qoşulma bitib: yenidən «Connect» edin.
Sağlamlıq
GET https://api.huqsi.az/healthz (açarsız):
{"status": "ok", "service": "huqsi-api", "version": "0.1.0", "db": "ok",
"graph_api": {"ok": true, "status": "ok", "detail": ""}}
graph_api.ok: false olduqda /v1/* 503 qaytarır. Kabinet və bu endpoint işləməyə davam edir.
GET https://api.huqsi.az/readyz hazırlıq yoxlamasıdır. Qanun bazasına real autentifikasiyalı sorğu göndərir və bunları
yoxlayır: baza işləyir və bizim açarımız qəbul olunur. Uğurda 200 {"status": "ready"}, əks halda
503 {"status": "not_ready", …} qayıdır.
Dəstək
api@huqsi.az — sorğunun vaxtını (UTC) və açarın prefiksini (hq_abcd…, tam açarı yox) yazın.