خطاها
همهی خطاها قالب یکسان JSON دارند با type، code، message، param و request_id؛ روی code تصمیم بگیر، نه message.
قالب خطا
نمونه — 400
{
"error": {
"type": "invalid_request_error",
"code": "parameter_invalid",
"message": "حداقل خرید استارز ۵۰ عدد است.",
"param": "quantity",
"request_id": "req_XZV2dfm7YHW6ECeAA1bW"
}
}code پایدار است و برای منطق برنامه است؛ message فارسی و برای نمایش است و ممکن است تغییر کند. request_id را در لاگ خودت نگه دار؛ پشتیبانی با آن درخواست را دقیق پیدا میکند.
کدهای HTTP
| HTTP | type | معنی |
|---|---|---|
| 400 | invalid_request_error | پارامتر یا بدنه نامعتبر |
| 401 | authentication_error | مشکل کلید |
| 402 | payment_error | موجودی کافی نیست |
| 403 | permission_error | scope یا وضعیت حساب |
| 404 | invalid_request_error | پیدا نشد (منابع دیگران هم همیشه 404 میدهند) |
| 409 | conflict_error | تداخل وضعیت یا idempotency |
| 429 | rate_limit_error | محدودیت نرخ |
| 5xx | api_error | خطای سرور؛ با همان Idempotency-Key دوباره بفرست |
کی دوباره تلاش کنم؟
روی 429 بعد از Retry-After، روی 5xx و قطعی شبکه با فاصلهی افزایشی (۱، ۲، ۴، ۸ ثانیه). درخواستهای POST را فقط با Idempotency-Key تکرار کن. روی 4xx دیگر تکرار نکن؛ درخواست را اصلاح کن.
