quickstart manifest errors webhooks api marketplace agents surfaces

Xato kodlari

Har bir xato bir xil shaklda keladi va nima qilish kerakligini aytadi:


{
  "error": {
    "code": "insufficient_scope",
    "message": "Bu amal uchun `runs:write` ruxsati kerak",
    "fix": "Integratsiya sozlamalarida shu scope'ni qo'shing va qayta ulaning",
    "docs_url": "https://agentfather.uz/docs/errors#insufficient_scope",
    "request_id": "req_9f2c…",
    "details": { "required_scope": "runs:write", "granted_scopes": ["runs:read"] }
  }
}

Kodlarni code bo'yicha ushlang — message matni o'zgarishi mumkin.

400 — so'rovda xato

Kod	Ma'nosi	Nima qilish
`bad_request`	Umumiy	`message` ga qarang
`invalid_request`	OAuth parametri yetishmayapti	Odatda `code_challenge` yoki `code_verifier`
`invalid_grant`	Kod/refresh token yaroqsiz	Avtorizatsiyani boshidan boshlang
`invalid_scope`	Noma'lum scope	`GET /oauth/scopes`
`invalid_redirect_uri`	Manzil ro'yxatda yo'q	Portal → Redirect URIs (to'liq mos kelishi kerak)
`unsupported_grant_type`		`authorization_code` yoki `refresh_token`
`unsupported_response_type`		Faqat `code`
`expired_consent_link`	Telegram'ga o'tadigan rozilik havolasi 10 daqiqada kuyadi	`authorize` havolasini qaytadan oching

401 — kim ekanligingiz aniqlanmadi

Kod	Ma'nosi	Nima qilish
`unauthorized`	Token yo'q, yaroqsiz yoki muddati o'tgan	Refresh bilan yangilang
`invalid_client`	`client_id`/`client_secret` noto'g'ri	Portal → Keys

Token muddati o'tishi normal holat — SDK avtomatik yangilaydi. Agar Token bekor qilingan (integratsiya kalitlari yangilangan) desa — kimdir sirni rotate qilgan, refresh bilan yangi token oling.

403 — huquq yetmaydi

Kod	Ma'nosi	Nima qilish
`insufficient_scope`	Scope so'ralmagan	`requested_scopes` ga qo'shing, qayta consent
`scope_denied_by_admin`	Tashkilot admini taqiqlagan	Admin bilan gaplashing
`tool_denied`	Tool taqiqlangan	Admin siyosati — `details.reason` da sabab
`app_suspended`	Integratsiya to'xtatilgan	Qo'llab-quvvatlash
`installation_suspended`	O'rnatish vaqtincha to'xtatilgan	Mijoz admini
`disposable_token_readonly`	iframe tokeni bilan yozmoqchi bo'ldingiz	Yozishni backend'dan bajaring
`admin_required`	Console amali admin talab qiladi
`not_a_developer`	Dasturchi hisobi yo'q	`POST /api/v1/dev/register`
`app_limit_reached`	Integratsiyalar chegarasi	Eskilarini o'chiring
`webhook_limit_reached`	Obunalar chegarasi	Bitta manzilga bir nechta hodisa yozing
`too_many_steps`	Bitta ishda 200+ qadam	Ishni bo'lib yuboring

404 — topilmadi

Kod	Izoh
`not_found`	Resurs yo'q yoki boshqa tashkilotga tegishli. Ikkinchi holatni ataylab ajratmaymiz — mavjudligini oshkor qilmaslik uchun

409 — ziddiyat

Kod	Ma'nosi	Nima qilish
`conflict`	Umumiy
`slug_taken`	Slug band	Boshqasini tanlang
`version_exists`	Versiya allaqachon bor	`version` ni oshiring — versiyalar o'zgarmas
`idempotency_key_reused`	Kalit boshqa tana bilan	Har yangi so'rovga yangi kalit (UUID)
`run_already_finished`	Ish tugagan	Yangi ish yarating
`too_many_active_runs`	5 tadan ortiq faol ish	Tugashini kuting
`approval_already_decided`	Tasdiq allaqachon hal qilingan
`step_write_conflict`	Parallel yozuv to'qnashuvi	Qadamlarni ketma-ket yuboring

422 — validatsiya

Kod	Ma'nosi	Nima qilish
`validation_error`	So'rov tanasi noto'g'ri	`details.fields` ga qarang
`invalid_manifest`	Manifest xatosi	`details.errors[].path` va `.fix`
`invalid_config`	Sozlamalar sxemaga mos emas	Manifest `config` bo'limi
`blocked_target`	Manzil taqiqlangan (SSRF)	Ochiq HTTPS manzil bering
`unknown_tool`	Bunday tool yo'q	`GET /api/v1/tools`
`review_requirements_missing`	Moderatsiya uchun ma'lumot yetishmayapti	`details.missing`

429 — chegara

Kod	Nima qilish
`rate_limited`	`Retry-After` sarlavhasini kuting. `details.limit_scope`: `installation` yoki `app`

5xx — bizning tomonda

Kod	Ma'nosi	Nima qilish
`internal_error`	Kutilmagan xato	Qayta urinib ko'ring; takrorlansa `request_id` bilan yozing
`agent_unreachable`	Agent javob bermadi	Endpoint ochiqmi, 30 soniyada javob beradimi
`llm_not_configured`	`inline` agent uchun model kaliti yo'q	Platforma `.env` → `LLM_API_KEY`
`llm_error`	Model provayderi xatosi	`details.body`

Agentingiz qaytaradigan xatolar

Run muvaffaqiyatsiz tugaganda o'z kodingizni bering — u mijozga va sizga ko'rinadi:


{ "status": "failed", "error_code": "quota_exceeded", "error_message": "Kunlik limit tugadi" }

Yaxshi error_message — foydalanuvchi o'qib nima qilishini tushunadigan matn. Traceback (most recent call last) emas.