# Lỗi

Định dạng phản hồi lỗi chuẩn và mọi mã trạng thái HTTP mà API sử dụng.

Source: https://support.toolingmetrics.com/vi/api/errors/
Updated: 2026-10-23

Phần lớn lỗi của API trả về thân JSON có mảng `errors`. Có một nhóm endpoint là ngoại lệ — đọc phần lưu ý về `404` bên dưới trước khi viết bộ phân tích lỗi dùng chung.

## Định dạng phản hồi lỗi

```json
{
  "errors": ["Description of what went wrong"]
}
```

Với lỗi kiểm tra dữ liệu ở yêu cầu ghi, mảng `errors` chứa một thông báo cho mỗi trường không đạt:

```json
{
  "errors": [
    "Name can't be blank",
    "Quantity must be greater than 0"
  ]
}
```

### Ngoại lệ `404`

Mọi phản hồi "không tìm thấy bản ghi" (ID không tồn tại, hoặc thuộc tổ chức khác) đều được trả về tường minh trong khối rescue của từng controller, và dùng khóa **số ít** `error` với giá trị là chuỗi — không phải mảng `errors` như mọi chỗ khác:

```json
{
  "error": "Couldn't find Part with 'id'=999"
}
```

Nếu mã xử lý lỗi của bạn chỉ kiểm tra `body.errors`, nó sẽ lặng lẽ bỏ sót các lỗi `404`. Hãy kiểm tra mã trạng thái trước, rồi rẽ nhánh theo khóa khi đọc riêng thân phản hồi `404`.

## Mã trạng thái HTTP

| Mã trạng thái | Ý nghĩa | Nguyên nhân thường gặp |
|---|---|---|
| `200 OK` | Yêu cầu thành công | GET, PATCH |
| `201 Created` | Đã tạo tài nguyên | POST |
| `204 No Content` | Đã xóa tài nguyên | DELETE |
| `401 Unauthorized` | Thiếu khóa hoặc khóa không hợp lệ, **hoặc** yêu cầu hợp lệ nhưng không đủ quyền | Cả hai trường hợp dùng chung mã này — xem [Xác thực](https://support.toolingmetrics.com/vi/api/authentication/) để biết cách phân biệt. Một `organization_id` không tồn tại cũng nhận lỗi không đủ quyền, như một tổ chức bạn không truy cập được. API này không dùng `403` |
| `404 Not Found` | Không tìm thấy tài nguyên | Sai ID, hoặc tài nguyên thuộc tổ chức khác. Thân phản hồi dùng khóa số ít `error` — xem ở trên |
| `422 Unprocessable Entity` | Kiểm tra dữ liệu không đạt | Thiếu trường bắt buộc, giá trị trường không hợp lệ |
| `429 Too Many Requests` | Vượt giới hạn tần suất | Xem [Giới hạn tần suất](https://support.toolingmetrics.com/vi/api/rate-limits/) |

`400 Bad Request` và `500 Internal Server Error` vẫn có thể xảy ra (JSON sai cú pháp, lỗi máy chủ ngoài dự kiến) nhưng không được các controller API xử lý riêng — đừng giả định thân phản hồi của chúng theo dạng `errors`/`error` ở trên.

## Xử lý lỗi

```python
import requests

response = requests.get(
    "https://api.toolingmetrics.com/v1/organizations/12/machines",
    headers={"Authorization": "Bearer YOUR_TOKEN"}
)

if response.status_code == 401:
    print("Check your API token, or your role for this resource")
elif response.status_code == 404:
    print("Not found:", response.json().get("error"))
elif response.status_code == 429:
    retry_after = response.headers.get("Retry-After", 60)
    print(f"Rate limited. Retry after {retry_after} seconds.")
elif not response.ok:
    errors = response.json().get("errors", [])
    print("API error:", errors)
else:
    data = response.json()
```