Các lỗi API đã biết trả về một body JSON với cấu trúc này:
{
"error": {
"message": "Human-readable description",
"code": "error_code"
}
}
Tham chiếu lỗi
400 Bad Request
| Mã | Nguyên nhân | Cách khắc phục |
|---|
invalid_json | Request body không phải JSON hợp lệ | Kiểm tra cú pháp JSON của bạn |
missing_model | Trường model bị thiếu hoặc không phải là chuỗi | Bao gồm "model": "provider/name" trong request body của bạn |
missing_input | Trường input bị thiếu hoặc không phải là object | Bao gồm "input": {...} trong request body của bạn |
invalid_input | Input không khớp với schema của model | Kiểm tra tài liệu tham chiếu API của model để biết các trường bắt buộc và giá trị hợp lệ |
model_not_found | Model ID không khớp với bất kỳ model nào có sẵn | Xem trang models để biết các Model ID hợp lệ |
401 Unauthorized
| Mã | Nguyên nhân | Cách khắc phục |
|---|
missing_api_key | Không có header Authorization hoặc định dạng sai | Bao gồm Authorization: Bearer sk-... trong request của bạn |
invalid_api_key | Key không hợp lệ, bị vô hiệu hóa hoặc đã hết hạn | Tạo key mới hoặc bật lại key hiện có trong Settings → API Keys |
402 Payment Required
| Mã | Nguyên nhân | Cách khắc phục |
|---|
insufficient_balance | Số dư của bạn quá thấp cho lần chạy này | Nạp thêm số dư trong Settings → Credits |
403 Forbidden
| Mã | Nguyên nhân | Cách khắc phục |
|---|
api_key_spend_limit_exceeded | Giới hạn chi tiêu trọn đời của key đã đạt đến | Tăng giới hạn chi tiêu trong Settings → API Keys |
ip_not_allowed | IP của bạn không nằm trong danh sách trắng của key | Thêm IP của bạn vào danh sách cho phép của key, hoặc xóa danh sách trắng |
429 Too Many Requests
| Mã | Nguyên nhân | Cách khắc phục |
|---|
RATE_LIMITED | Quá nhiều request trong một khoảng thời gian ngắn | Chờ và thử lại. Xem rate limits |
USAGE_EXCEEDED | Hạn ngạch sử dụng của key đã cạn | Liên hệ hỗ trợ hoặc tạo key mới |
404 Not Found
| Mã | Nguyên nhân | Cách khắc phục |
|---|
run_not_found | Không có run nào với ID này cho tài khoản của bạn | Kiểm tra ID run là chính xác và đã được tạo bằng API key này |
500 Internal Server Error
Một lỗi không mong đợi từ phía chúng tôi. Nếu tình trạng này vẫn tiếp diễn, hãy liên hệ support@runbase.net.
Xử lý lỗi trong code
response=$(curl -s -w "\n%{http_code}" https://runbase.net/api/v1/runs \
-H "Authorization: Bearer $RUNBASE_API_KEY" \
-H "Content-Type: application/json" \
-d '{"model": "google/nano-banana-2", "input": {"prompt": "test"}}')
http_code=$(echo "$response" | tail -1)
body=$(echo "$response" | head -1)
if [ "$http_code" -ne 201 ]; then
echo "Error $http_code: $(echo $body | jq -r '.error.message')"
fi
Đối với các lỗi 429, hãy triển khai exponential backoff — chờ 1s, sau đó 2s, rồi 4s trước khi thử lại.
