درک کدهای خطا و پیامهای بازگشتی از API راهیانا برای عیبیابی و مدیریت بهتر خطاها.
تمام پاسخهای خطا از API راهیانا، صرف نظر از کد وضعیت HTTP، دارای یک ساختار JSON استاندارد هستند. این ساختار به شما کمک میکند تا اطلاعات دقیقی درباره خطا به دست آورید.
{
"error": {
"message": "توضیح قابل فهم برای انسان درباره خطا.",
"type": "نوع کلی خطا (مثلاً invalid_request_error)",
"param": "پارامتر درخواست که باعث خطا شده (در صورت وجود)",
"code": "کد داخلی و خاص خطا (مثلاً missing_required_parameter)"
}
}
provider_error
در جدول زیر، برخی از کدهای وضعیت HTTP رایج که ممکن است از API راهیانا دریافت کنید، به همراه توضیحات و نمونه پاسخ خطا آورده شده است:
کد HTTP | وضعیت | پیام فارسی | توضیحات |
---|---|---|---|
400 | Bad Request | درخواست نامعتبر | درخواست ارسال شده توسط کلاینت دارای ساختار اشتباه، پارامترهای نامعتبر یا ناقص است. |
401 | Unauthorized | احراز هویت ناموفق | کلید API ارائهنشده یا نامعتبر است. |
403 | Forbidden | دسترسی ممنوع | کلید API شما اجازه دسترسی به عملیات درخواستی را ندارد. |
404 | Not Found | منبع یافت نشد | منبع درخواستی یافت نشد (مثلاً مدل نامعتبر). |
429 | Too Many Requests | درخواستهای بیش از حد | شما از محدودیت نرخ (Rate Limit) یا محدودیت مصرف روزانه/ماهانه خود فراتر رفتهاید. |
500 | Internal Server Error | خطای داخلی سرور | یک خطای پیشبینی نشده در سمت سرور رخ داده است. تیم ما از این موضوع مطلع شده و در حال بررسی آن است. |
درخواست ارسال شده توسط کلاینت دارای ساختار اشتباه، پارامترهای نامعتبر یا ناقص است.
نمونه پاسخ خطا:
{
"error": {
"message": "پارامتر ضروری 'model' در درخواست ارسال نشده است.",
"type": "invalid_request_error",
"param": "model",
"code": "missing_required_parameter"
}
}
کلید API ارائهنشده یا نامعتبر است.
نمونه پاسخ خطا:
{
"error": {
"message": "کلید API نامعتبر است.",
"type": "authentication_error",
"param": null,
"code": "invalid_api_key"
}
}
کلید API شما اجازه دسترسی به عملیات درخواستی را ندارد.
نمونه پاسخ خطا:
{
"error": {
"message": "شما اجازه دسترسی به این مدل را ندارید.",
"type": "permission_error",
"param": null,
"code": "permission_denied"
}
}
منبع درخواستی یافت نشد (مثلاً مدل نامعتبر).
نمونه پاسخ خطا:
{
"error": {
"message": "مدل 'invalid-model' یافت نشد.",
"type": "invalid_request_error",
"param": "model",
"code": "model_not_found"
}
}
شما از محدودیت نرخ (Rate Limit) یا محدودیت مصرف روزانه/ماهانه خود فراتر رفتهاید.
نمونه پاسخ خطا:
{
"error": {
"message": "محدودیت نرخ شما برای مدل 'gpt-3.5-turbo' در یک دقیقه گذشته فراتر رفته است. لطفاً بعداً دوباره تلاش کنید.",
"type": "rate_limit_error",
"param": null,
"code": "rate_limit_exceeded"
}
}
یک خطای پیشبینی نشده در سمت سرور رخ داده است. تیم ما از این موضوع مطلع شده و در حال بررسی آن است.
نمونه پاسخ خطا:
{
"error": {
"message": "یک خطای داخلی در سرور رخ داده است. لطفاً بعداً دوباره تلاش کنید یا با پشتیبانی تماس بگیرید.",
"type": "server_error",
"param": null,
"code": "internal_server_error"
}
}
علاوه بر خطاهای استاندارد HTTP، API راهیانا ممکن است کدهای خطای خاص خود را نیز برگرداند. این کدها معمولاً با پیشوند
RAHYANA_
provider_error
کد خطا (Error Code) | کد HTTP | پیام فارسی | توضیحات |
---|---|---|---|
RAHYANA_INSUFFICIENT_CREDITS | 403 | اعتبار ناکافی | حساب شما اعتبار کافی برای انجام درخواست را ندارد. لطفاً حساب خود را شارژ کنید. |
RAHYANA_MODEL_NOT_AVAILABLE | 404 | مدل در دسترس نیست | مدل درخواستی در حال حاضر در پلتفرم راهیانا در دسترس نیست. |
RAHYANA_PROVIDER_ERROR | 4xx/5xx | خطا از سمت ارائهدهنده | یک خطای عمومی از سمت ارائهدهنده LLM (مانند OpenAI یا Anthropic) بازگردانده شده است. |
RAHYANA_INVALID_PROMPT | 400 | پرامپت نامعتبر | ساختار پرامپت ارسالی نامعتبر است یا با الزامات مدل مطابقت ندارد. |
RAHYANA_MAX_TOKENS_EXCEEDED | 400 | حداکثر توکن تجاوز شد | تعداد توکنهای درخواستی از حداکثر توکنهای مجاز برای مدل فراتر رفته است. |
RAHYANA_PROVIDER_REQUEST_FAILED | 4xx/5xx | درخواست به ارائهدهنده LLM ناموفق بود | درخواست به ارائهدهنده پاییندستی LLM (مانند OpenRouter) با خطا مواجه شد. کد وضعیت HTTP و پیام خطای دقیق از ارائهدهنده برگردانده میشود. |
RAHYANA_INTERNAL_SERVER_ERROR | 500 | یک خطای غیرمنتظره در سرور رخ داد | یک خطای پیشبینی نشده و عمومی در سمت سرور راهیانا رخ داده است. تیم ما از این موضوع مطلع شده و در حال بررسی آن است. |
RAHYANA_INSUFFICIENT_CREDITS
(اعتبار ناکافی)کد HTTP: 403
حساب شما اعتبار کافی برای انجام درخواست را ندارد. لطفاً حساب خود را شارژ کنید.
نمونه پاسخ خطا:
{
"error": {
"message": "اعتبار حساب شما برای انجام این درخواست کافی نیست. لطفاً حساب خود را شارژ کنید.",
"type": "insufficient_credits",
"param": null,
"code": "RAHYANA_INSUFFICIENT_CREDITS"
}
}
RAHYANA_MODEL_NOT_AVAILABLE
(مدل در دسترس نیست)کد HTTP: 404
مدل درخواستی در حال حاضر در پلتفرم راهیانا در دسترس نیست.
نمونه پاسخ خطا:
{
"error": {
"message": "مدل 'openai/gpt-4o' در حال حاضر در دسترس نیست.",
"type": "model_unavailable",
"param": "model",
"code": "RAHYANA_MODEL_NOT_AVAILABLE"
}
}
RAHYANA_PROVIDER_ERROR
(خطا از سمت ارائهدهنده)کد HTTP: 4xx/5xx
یک خطای عمومی از سمت ارائهدهنده LLM (مانند OpenAI یا Anthropic) بازگردانده شده است.
نمونه پاسخ خطا:
{
"error": {
"message": "خطا از سمت ارائهدهنده: An unexpected error occurred.",
"type": "provider_error",
"param": null,
"code": "RAHYANA_PROVIDER_ERROR"
}
}
RAHYANA_INVALID_PROMPT
(پرامپت نامعتبر)کد HTTP: 400
ساختار پرامپت ارسالی نامعتبر است یا با الزامات مدل مطابقت ندارد.
نمونه پاسخ خطا:
{
"error": {
"message": "پرامپت ارسالی دارای فرمت نامعتبر است. محتوای پیام کاربر نمیتواند خالی باشد.",
"type": "invalid_request_error",
"param": "prompt",
"code": "RAHYANA_INVALID_PROMPT"
}
}
RAHYANA_MAX_TOKENS_EXCEEDED
(حداکثر توکن تجاوز شد)کد HTTP: 400
تعداد توکنهای درخواستی از حداکثر توکنهای مجاز برای مدل فراتر رفته است.
نمونه پاسخ خطا:
{
"error": {
"message": "حداکثر توکنهای درخواستی (max_tokens) از محدودیت مدل فراتر رفته است.",
"type": "invalid_request_error",
"param": "max_tokens",
"code": "RAHYANA_MAX_TOKENS_EXCEEDED"
}
}
RAHYANA_PROVIDER_REQUEST_FAILED
(درخواست به ارائهدهنده LLM ناموفق بود)کد HTTP: 4xx/5xx
درخواست به ارائهدهنده پاییندستی LLM (مانند OpenRouter) با خطا مواجه شد. کد وضعیت HTTP و پیام خطای دقیق از ارائهدهنده برگردانده میشود.
نمونه پاسخ خطا:
{
"error": {
"message": "درخواست به ارائه دهنده LLM ناموفق بود: 401 - کلید API ارائهدهنده نامعتبر است.",
"type": "provider_error",
"param": null,
"code": "RAHYANA_PROVIDER_REQUEST_FAILED",
"provider_error": {
"message": "Invalid API key for specified model provider.",
"type": "authentication_error",
"code": "invalid_provider_key",
"status_code": 401
}
}
}
RAHYANA_INTERNAL_SERVER_ERROR
(یک خطای غیرمنتظره در سرور رخ داد)کد HTTP: 500
یک خطای پیشبینی نشده و عمومی در سمت سرور راهیانا رخ داده است. تیم ما از این موضوع مطلع شده و در حال بررسی آن است.
نمونه پاسخ خطا:
{
"error": {
"message": "یک خطای داخلی و غیرمنتظره در سرور رخ داده است. لطفاً بعداً دوباره تلاش کنید یا با پشتیبانی تماس بگیرید.",
"type": "server_error",
"param": null,
"code": "RAHYANA_INTERNAL_SERVER_ERROR"
}
}