Errors
All errors have one shape:
{"error": "rate_limited", "message": "Dəqiqəlik limit aşıldı. …"}
error is a stable machine code. message is a human explanation, in Azerbaijani.
| HTTP | error |
Cause | What to do |
|---|---|---|---|
| 401 | unauthorized |
No X-API-Key (or OAuth token), or the key is unknown |
Check the header; keys start with hq_ |
| 401 | invalid_token |
MCP: the OAuth access token is unknown, expired, or its connection was revoked or ended | The client refreshes or asks you to «Connect» again |
| 401 | key_revoked |
The key was revoked | Create a new key in the dashboard |
| 401 | key_expired |
The key's lifetime ended (plans with key lifetime) | Press «Renew» next to the key in the dashboard |
| 403 | forbidden |
The endpoint is closed for your plan | Upgrade the plan (Limits) |
| 404 | not_found |
No such article, or a malformed id | Take article_id from a search result |
| 422 | validation_error |
Invalid request parameters | Fix the field named in message |
| 429 | rate_limited |
The account's per-minute limit (shared by all keys and apps) | Wait Retry-After seconds |
| 429 | ip_rate_limited |
The per-IP ceiling | Wait Retry-After seconds |
| 429 | quota_exceeded |
The account's monthly quota is used up | Wait for next month or upgrade |
| 503 | upstream_unavailable |
The law database does not answer | Retry after 30 s; the request is not charged |
On MCP the same codes come back as the tool's error text, code: message (isError: true).
MCP and OAuth
A /mcp request without credentials returns 401 with
WWW-Authenticate: Bearer resource_metadata="https://api.huqsi.az/.well-known/oauth-protected-resource/mcp", scope="read".
This response starts the OAuth sign-in in Claude.ai, ChatGPT and other clients. The OAuth endpoints (/oauth/token,
/oauth/register, …) use the standard OAuth error codes (invalid_grant, invalid_client_metadata, …).
invalid_grant on refresh means the connection has ended: connect again.
Health
GET https://api.huqsi.az/healthz (no key) is the liveness check. GET https://api.huqsi.az/readyz is the readiness check: it
makes an authenticated call to the law database. It returns 200 {"status": "ready"} or
503 {"status": "not_ready", …}.
Support
api@huqsi.az: include the time of the request (UTC) and the key prefix (hq_abcd…), never
the full key.