API و توسعهدهندگان
خطاها
API برای موفقیت کدهای 2xx و برای خطا کدهای 4xx و 5xx برمیگرداند. بدنه همه خطاها ساختار یکسانی دارد، پس کافی است یک بار مدیریتش کنید.
ساختار خطا#
JSON
{
"error": {
"code": "VALIDATION",
"message": "حداکثر ۱۲۰ کاراکتر مجاز است",
"fields": { "title": "حداکثر ۱۲۰ کاراکتر مجاز است" }
}
}| فیلد | توضیح |
|---|---|
code | کد ثابت انگلیسی. منطق برنامه را روی این فیلد بنا کنید؛ تغییر نمیکند. |
message | توضیح فارسی برای نمایش به کاربر. ممکن است متنش بهتر شود، پس با آن مقایسه نکنید. |
fields | فقط در خطاهای اعتبارسنجی: پیام هر فیلد، به تفکیک مسیر آن (مثل socials.discord). |
کدهای وضعیت#
| HTTP | معنی | کار درست |
|---|---|---|
200 / 201 | موفق / ساخته شد | — |
204 | موفق، بدون بدنه (حذف) | — |
400 | ورودی نامعتبر | fields را بخوانید و ورودی را اصلاح کنید؛ تکرار بیفایده است. |
401 | کلید ارسال نشده، نامعتبر یا باطلشده | کلید را بررسی کنید. |
403 | کلید معتبر است ولی اجازه این کار را ندارد | دسترسی کلید یا نقش سازنده را بررسی کنید. |
404 | سرور یا مورد پیدا نشد | نامک را بررسی کنید؛ سرورهای تأییدنشده یا تعلیقشده در مسیرهای خواندنی دیده نمیشوند. |
429 | سقف درخواست پر شده | به اندازه Retry-After صبر کنید. |
500 / 503 | خطای سمت گیم روت | با فاصله افزایشی دوباره تلاش کنید. |
فهرست کدهای خطا#
| کد | HTTP | توضیح |
|---|---|---|
API_KEY_REQUIRED | 401 | این مسیر بدون کلید کار نمیکند (مسیرهای مدیریتی و /me). |
INVALID_API_KEY | 401 | کلید با قالب gr_live_… نیست یا وجود ندارد. |
API_KEY_REVOKED | 401 | کلید باطل شده است. |
ACCOUNT_BANNED | 403 | حساب سازنده کلید مسدود است. |
INSUFFICIENT_SCOPE | 403 | کلید دسترسی لازم (مثلاً news:write) را ندارد. |
KEY_NOT_SERVER_BOUND | 403 | برای مدیریت، کلید حساب کافی نیست؛ کلید سرور لازم است. |
KEY_SERVER_MISMATCH | 403 | کلید برای سرور دیگری ساخته شده است. |
NO_SERVER_PERMISSION | 403 | سازنده کلید دیگر مجوز لازم را در تیم سرور ندارد. |
SERVER_NOT_FOUND | 404 | سروری با این نامک یا شناسه نیست، یا هنوز تأیید نشده است. |
NOT_FOUND | 404 | مورد دیگری (مثلاً خبر) پیدا نشد. |
VALIDATION | 400 | ورودی با قواعد نمیخواند؛ جزئیات در fields. |
INVALID_MEDIA | 400 | imageUrl تصویری نیست که در پنل گیم روت بارگذاری شده باشد. |
RATE_LIMITED | 429 | سقف درخواست در دقیقه پر شده است. |
INTERNAL | 500 | خطای پیشبینینشده. اگر تکرار شد گزارش دهید. |
مدیریت خطا در کد#
JavaScript
async function api(path, init = {}) {
const res = await fetch(`https://gameroute.ir/api/v1${path}`, {
...init,
headers: { Authorization: `Bearer ${process.env.GAMEROUTE_API_KEY}`, 'Content-Type': 'application/json', ...init.headers },
});
if (res.status === 204) return null;
const body = await res.json();
if (!res.ok) {
const err = new Error(body.error.message);
err.code = body.error.code;
err.status = res.status;
err.fields = body.error.fields;
throw err;
}
return body;
}
try {
await api('/servers/iran-craft/news', { method: 'POST', body: JSON.stringify({ body: 'سلام' }) });
} catch (e) {
if (e.code === 'NO_SERVER_PERMISSION') console.error('نقش سازنده کلید تغییر کرده است');
else throw e;
}Python
import requests
class GamerouteError(Exception):
def __init__(self, status, code, message, fields=None):
super().__init__(message)
self.status, self.code, self.fields = status, code, fields or {}
def api(method, path, **kw):
res = requests.request(method, f"https://gameroute.ir/api/v1{path}", timeout=10, **kw)
if res.status_code == 204:
return None
body = res.json()
if not res.ok:
e = body["error"]
raise GamerouteError(res.status_code, e["code"], e["message"], e.get("fields"))
return body