Mã lỗi

Khả dụng

Mô hình lỗi thống nhất và cách xử lý.

{
  "error": {
    "type": "conflict",
    "code": "insufficient_inventory",
    "message": "Không đủ tồn để giữ chỗ",
    "param": "quantity",
    "request_id": "req_9f2b…",
    "doc_url": "https://creator.poroai.life/developers/docs/errors#insufficient_inventory"
  }
}

HTTP	type	Khi nào xảy ra
401	authentication_error	Thiếu khoá, khoá sai hoặc đã thu hồi
403	permission_error	Khoá không có quyền với tài nguyên này
404	not_found	Tài nguyên không tồn tại trong tổ chức của bạn
400	invalid_request	Thiếu tham số, sai định dạng, thiếu Idempotency-Key
409	conflict	Xung đột nghiệp vụ, ví dụ không đủ tồn
409	idempotency_error	Cùng Idempotency-Key nhưng body khác lần gọi trước
429	rate_limit_error / quota_exceeded	Vượt giới hạn tần suất hoặc hạn mức tài nguyên
500	api_error	Lỗi phía PORO — nên thử lại
502	upstream_error	Hệ thống của khách hàng phía sau lỗi hoặc quá hạn

Luôn gửi kèm request_id khi báo lỗi — chúng tôi tra được toàn bộ vòng đời của lệnh gọi đó.

Nên thử lại lỗi nào

Thử lại: 429 và mọi lỗi 5xx, với backoff mũ.
Không thử lại: 400, 401, 403, 404, 409 — cần sửa request.
Lệnh ghi luôn kèm Idempotency-Key nên việc thử lại là an toàn.