Lỗi

Mọi phản hồi 4xx và 5xx của API có Content-Type: application/problem+json theo RFC 9457. Chương trình của bạn nên rẽ nhánh theo code, một giá trị ổn định, và không phân tích câu chữ của title hay detail.

Dạng của một lỗi

{
  "type": "https://docs.dongtien.pro/errors/validation_failed",
  "title": "Request validation failed",
  "status": 422,
  "detail": "Tham số truy vấn không hợp lệ.",
  "code": "validation_failed",
  "request_id": "req_0f5k2m9q4h7t3n8r6v1w0x5yzd",
  "retryable": false,
  "errors": [
    {
      "pointer": "#/query/limit",
      "detail": "Số phần tử mỗi trang phải từ 1 đến 100.",
      "code": "too_small"
    }
  ]
}

Trường	Ý nghĩa
type	Địa chỉ trang mô tả lỗi, luôn có dạng https://docs.dongtien.pro/errors/<code>.
title	Tiêu đề tiếng Anh, ổn định theo từng code.
status	Mã HTTP, trùng với trạng thái của phản hồi.
detail	Giải thích riêng cho lần lỗi này; không lộ chi tiết nội bộ.
code	Mã lỗi ổn định, viết snake_case. Đây là trường để chương trình rẽ nhánh.
request_id	Mã yêu cầu req_…, cũng có ở header X-Request-Id. Gửi kèm khi liên hệ hỗ trợ.
retryable	true nếu gửi lại cùng yêu cầu có thể thành công.
retry_after	Số giây nên chờ trước khi gửi lại, khi áp dụng.
errors	Danh sách lỗi theo từng trường, chỉ có ở lỗi kiểm tra đầu vào.

Danh mục đầy đủ các mã, mỗi mã một trang, nằm ở Mã lỗi. Thêm mã lỗi mới là thay đổi không phá vỡ (xem phiên bản), nên mã của bạn cần một nhánh mặc định cho code chưa biết.

Đọc errors[]

Mỗi phần tử của errors chỉ ra một trường sai: pointer là vị trí, detail mô tả lỗi và code là mã ngắn của trường (ví dụ too_small, invalid_format). pointer có một trong bốn dạng:

Dạng	Chỉ tới
/company_id, /lines/0/amount	Trường trong thân JSON, theo RFC 6901 JSON Pointer.
#/query/<tên>	Tham số truy vấn, ví dụ #/query/limit.
#/path/<tên>	Tham số trong đường dẫn.
#/header/<tên>	Một header, ví dụ #/header/Idempotency-Key.

Ở giao diện nhập liệu, dùng pointer để gắn thông báo lên đúng ô; ở mã tích hợp, ghi cả pointer và detail vào log.

Có nên thử lại không

1. Đọc retryable. Nếu là false, sửa yêu cầu rồi mới gửi lại; gửi lại nguyên văn chỉ nhận cùng lỗi.
2. Nếu là true, chờ retry_after giây (hoặc header Retry-After), rồi thử lại với độ trễ tăng dần và có giới hạn số lần.
3. Với route ghi, luôn gửi kèm Idempotency-Key và dùng lại đúng khoá ở mọi lần thử. Xem Idempotency.
4. Lỗi 4xx khác 429 thường là lỗi của yêu cầu, không phải sự cố tạm thời.

Không có phản hồi nào (đứt kết nối, hết thời gian) không phải là một lỗi RFC 9457; SDK báo riêng bằng ConnectionError ở TypeScript và DongTienConnectionError ở Python.

Lỗi trong SDK

SDK biến mọi phản hồi không thành công thành ApiError với status, code, title, detail, requestId (request_id ở Python), errors, retryable và retryAfter (retry_after). Xem SDK TypeScript và SDK Python.

Các lỗi bạn gặp sớm nhất

HTTP	Mã lỗi	Thử lại	Ý nghĩa
401	unauthenticated	không	Cần đăng nhập
401	invalid_api_key	không	Khoá API không hợp lệ
403	scope_not_allowed	không	Phạm vi khoá không cho phép route này
422	validation_failed	không	Dữ liệu không hợp lệ
400	invalid_cursor	không	Con trỏ phân trang không hợp lệ
429	rate_limited	có	Gọi quá nhanh
500	internal_error	có	Lỗi hệ thống
503	service_unavailable	có	Dịch vụ tạm thời không khả dụng

Khi liên hệ hỗ trợ

Gửi request_id của lần lỗi (và DongTien-Version bạn đã dùng). Không gửi khoá API.