Hoạt động · 2026-09-01 · HippoAPI Documentation Team
Lỗi và thử lại
Phân loại các lỗi API, thu thập bằng chứng hữu ích và chỉ thử lại các yêu cầu tạm thời an toàn để lặp lại.
Hình dạng phản hồi lỗi
Phản hồi không phải 2xx sử dụng đối tượng lỗi có thông báo mà con người có thể đọc được và có thể bao gồm loại, mã hoặc ID yêu cầu. Hãy coi trạng thái HTTP là tín hiệu phân loại đầu tiên và giữ nguyên ID yêu cầu khi có.
{
"error": {
"message": "Error description (request id: ...)",
"type": "new_api_error",
"code": ""
}
}Mã trạng thái và hành động
| Status | Nghĩa | Hành động ứng dụng |
|---|---|---|
| 400 | Yêu cầu, mô hình, trường hoặc tham số không được hỗ trợ không hợp lệ. | Sửa yêu cầu. Đừng thử lại cùng một cơ thể không thay đổi. |
| 401 | Khóa API bị thiếu, không đúng định dạng, hết hạn, bị vô hiệu hóa hoặc không hợp lệ. | Sửa hoặc xoay phím. Đừng tự động thử lại. |
| 403 | Tài khoản, khóa, IP, nhóm hoặc mô hình không được phép. | Xem lại các biện pháp kiểm soát quyền truy cập và tính khả dụng của mô hình. |
| 402 | Số dư hoặc hạn ngạch không đủ. | Xem lại hạn mức Ví và khóa trước khi gửi thêm yêu cầu. |
| 404 | Không tìm thấy tài nguyên điểm cuối hoặc mô hình. | Kiểm tra URL cơ sở, đường dẫn điểm cuối và mã nhận dạng mô hình chính xác. |
| 429 | Tỷ lệ yêu cầu hiện tại hoặc tỷ lệ đồng thời quá cao. | Lùi lại với jitter và giảm đồng thời. |
| 5xx | Nền tảng hoặc nhà cung cấp ngược dòng bị lỗi. | Thử lại các yêu cầu an toàn với giới hạn nỗ lực nghiêm ngặt; giữ lại ID yêu cầu. |
Sử dụng thời gian chờ lũy thừa có giới hạn
Chỉ thử lại các lỗi có thể tạm thời: lỗi kết nối, HTTP 429 và phản hồi 5xx đã chọn. Thêm jitter ngẫu nhiên để nhiều công nhân không thử lại cùng một lúc. Đặt cả số lần thử tối đa và thời hạn tổng thể.
const delaysMs = [500, 1000, 2000]
for (let attempt = 0; attempt <= delaysMs.length; attempt++) {
try {
return await callHippoAPI()
} catch (error) {
const status = error?.status
const retryable = status === 429 || (status >= 500 && status < 600)
if (!retryable || attempt === delaysMs.length) throw error
const jitter = Math.floor(Math.random() * 250)
await new Promise((resolve) => setTimeout(resolve, delaysMs[attempt] + jitter))
}
}Ghi lại bằng chứng mà không cần ghi lại bí mật
Không ghi lại các header Authorization, khóa API đầy đủ hoặc lời nhắc hoàn chỉnh có chứa dữ liệu cá nhân, bí mật hoặc được quản lý. Xử lý lại trước khi chuyển tiếp lỗi tới các công cụ quan sát.
- Dấu thời gian UTC và ID theo dõi ứng dụng.
- ID yêu cầu HippoAPI khi có.
- Phương thức HTTP và đường dẫn điểm cuối.
- Mã định danh mô hình, mã trạng thái, thời lượng và thử lại.
- Bản tóm tắt lỗi đã được biên tập lại.
Trước khi liên hệ với bộ phận hỗ trợ
Tái tạo sự cố với yêu cầu an toàn nhỏ nhất, xác nhận mô hình xuất hiện trong GET /v1/models và kiểm tra Nhật ký sử dụng. Sau đó, cung cấp dấu thời gian, điểm cuối, mô hình, trạng thái HTTP, ID yêu cầu và bản tóm tắt yêu cầu đã được xử lý lại tới [email protected].
Không bao gồm khóa API của bạn. Nếu bạn đã chia sẻ hoặc tiết lộ nó, hãy thu hồi nó trước khi tiếp tục điều tra.