Lỗi

Lỗi của API V1 công khai Sellfern dùng mã ổn định và có thể đọc được bằng máy để các tích hợp và AI agent có thể phục hồi an toàn.

Trạng thái	Mã	Ý nghĩa	Cách xử lý được khuyến nghị
`400`	`validation_error`	Tham số hoặc body của yêu cầu không hợp lệ.	Sửa yêu cầu trước khi thử lại.
`401`	`unauthorized`	Khóa API bị thiếu, không hợp lệ, hết hạn hoặc đã thu hồi.	Dừng lại và yêu cầu khóa API hợp lệ.
`403`	`missing_scope`	Khóa API thiếu phạm vi cần thiết.	Yêu cầu khóa có phạm vi bổ sung tối thiểu.
`404`	`not_found`	Tài nguyên không tồn tại hoặc nằm ngoài tổ chức của khóa API.	Không suy luận về quyền sở hữu giữa các tổ chức.
`422`	`idempotency_conflict`	Khóa idempotency đã được dùng lại với một yêu cầu khác.	Tạo khóa mới cho thao tác logic mới.
`429`	`rate_limited`	Khóa API vượt quá giới hạn tốc độ.	Lùi lại và thử lại sau.

Cấu trúc phản hồi lỗi

error.details được đưa vào khi có dữ liệu khắc phục có cấu trúc. meta.request_id luôn an toàn để ghi log và chia sẻ với bộ phận hỗ trợ Sellfern.

{
  "success": false,
  "error": {
    "code": "missing_scope",
    "message": "API key lacks the required scope for this endpoint.",
    "details": {
      "required_scope": "orders:read"
    }
  },
  "meta": {
    "request_id": "req_01HX..."
  }
}

Hướng dẫn cho nhà phát triển

Tích hợp

Cấu trúc phản hồi lỗi