---
title: خطاها | Stard API
url: https://stard-market.ir/docs/errors
markdown: https://stard-market.ir/docs/errors.md
language: fa
updated: 2026-11-18
description: همه‌ی خطاها قالب یکسان JSON دارند با type، code، message، param و request_id؛ روی code تصمیم بگیر، نه message.
---

# خطاها

> همه‌ی خطاها قالب یکسان JSON دارند با type، code، message، param و request_id؛ روی code تصمیم بگیر، نه message.

## قالب خطا

**نمونه — 400**

```json
{
  "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` دیگر تکرار نکن؛ درخواست را اصلاح کن.
