Xử lý lỗi

ANKK Public API trả về các mã trạng thái HTTP tiêu chuẩn kèm theo thân lỗi JSON chi tiết.

📌 Lược đồ lỗi tiêu chuẩn

Tất cả các phản hồi lỗi đều tuân theo sơ đồ sau:

{
  "error": "idempotency_conflict",
  "message": "The idempotency key was already used with a different request payload.",
  "param": "idempotency_key"
}

🚦 Tham chiếu mã trạng thái HTTP

Mã trạng thái	Mã lỗi	Ý nghĩa & Hành động khuyến nghị
`400 Bad Request`	`invalid_input`, `validation_failed`	Thân yêu cầu hoặc tham số bị sai định dạng. Hãy sửa payload.
`401 Unauthorized`	`unauthorized`, `invalid_api_key`	Thiếu khóa API hoặc khóa API không hợp lệ.
`403 Forbidden`	`insufficient_scope`, `quota_exceeded`	Thiếu scope hoặc vượt quá hạn ngạch gói.
`404 Not Found`	`not_found`	Không tìm thấy tài nguyên (`content_id`, `connection_id`).
`409 Conflict`	`idempotency_conflict`	Khóa Idempotency được tái sử dụng với payload không khớp.
`423 Locked`	`brand_locked`	Thương hiệu bị khóa do thanh toán hoặc chính sách. Hãy kiểm tra mục Thanh toán.
`429 Too Many Requests`	`rate_limited`	Vượt quá giới hạn tốc độ. Hãy thử lại theo `Retry-After`.
`500 Server Error`	`internal_server_error`	Lỗi máy chủ nội bộ. Có thể thử lại với thời gian chờ tăng dần.
`503 Service Unavailable`	`sns_provider_unavailable`	Dịch vụ SNS bên ngoài gặp sự cố. Có thể thử lại sau.

🔍 Các ví dụ lỗi nghiệp vụ phổ biến

1. 403 Thiếu Scope

{
  "error": "insufficient_scope",
  "message": "The API key does not have the required 'publishing:create' scope."
}

2. 409 Xung đột Idempotency

{
  "error": "idempotency_conflict",
  "message": "Idempotency key 'launch-001' is already bound to a different request hash.",
  "param": "idempotency_key"
}

3. 400 Xác thực phương tiện không thành công

{
  "error": "sns_content_media_maximum_exceeded",
  "message": "Bluesky supports a maximum of 4 images per post.",
  "param": "media"
}

🔁 Chiến lược thử lại an toàn

Có thể thử lại (5xx, Hết thời gian mạng): Gửi lại bằng cách sử dụng chính xác cùng một idempotency_key với cơ chế exponential jitter backoff.
Không thể thử lại (400, 401, 403, 404, 409): Sửa đổi mã phía khách hàng hoặc payload, sau đó cấp lại dưới một khóa idempotency mới.

🔗 Tài liệu liên quan