Lỗi

Lỗi dùng mã trạng thái HTTP và nội dung theo RFC 9457 với Content-Type: application/problem+json:

{
  "type": "https://bonafidesign.com/problems/validation-error",
  "title": "Validation failed",
  "status": 422,
  "detail": "The request is invalid.",
  "errors": [
    { "pointer": "/recipients/0/email", "message": "Invalid email address" },
    { "pointer": "/recipients", "message": "Missing recipient for role 'company'." },
    { "pointer": "/recipients/1/role", "message": "Unknown role 'cfo'.", "hint": "Template roles: client, company" }
  ],
  "requestId": "req_V1StGXR8Z5jdHi6BmyT2"
}

Thành phần	Ý nghĩa
`type`	Định danh ổn định: `https://bonafidesign.com/problems/<slug>`. Hãy rẽ nhánh theo giá trị này (hoặc theo slug), không theo `title` hay `detail`
`title`	Tóm tắt ngắn về loại lỗi
`status`	Mã trạng thái HTTP
`detail`	Giải thích dễ đọc về lần xảy ra lỗi này
`errors`	Các vấn đề xác thực dữ liệu: `pointer` (một JSON Pointer trỏ vào nội dung yêu cầu, hoặc vào query hay các biến), `message`, `hint` tùy chọn
`requestId`	Cũng có trong header `x-request-id`. Hãy cung cấp giá trị này cho bộ phận hỗ trợ
`upgradeUrl`	Với các giới hạn theo gói (`402`, `403 plan-upgrade-required`): nơi để thêm thẻ hoặc nâng cấp

Mọi vấn đề xác thực dữ liệu của một yêu cầu đều được báo cùng lúc, để client có thể hiển thị từng vấn đề bên cạnh đúng trường tương ứng.

Các loại lỗi

Trạng thái	Slug	Khi nào
400	`bad-request`	Yêu cầu sai định dạng, chẳng hạn nội dung không phải JSON hợp lệ
401	`unauthorized`	Thông tin xác thực bị thiếu, sai định dạng, đã thu hồi hoặc đã hết hạn
402	`payment-required`	Một không gian làm việc Free đã hoàn tất hết số phong bì được bao gồm trong kỳ này; hãy thêm thẻ hoặc nâng cấp (chế độ thử nghiệm không bị ảnh hưởng)
403	`forbidden`	Đã xác thực nhưng không được phép: thiếu quyền, dùng khóa API trên endpoint chỉ dành cho bảng điều khiển, yêu cầu cross-site
403	`plan-upgrade-required`	Tính năng không có trong gói của không gian làm việc
403	`verification-required`	Người ký gửi trước khi xác minh mã dùng một lần
404	`not-found`	Tài nguyên không tồn tại trong tổ chức của bạn, hoặc đường dẫn không tồn tại
409	`invalid-state`	Hành động không phù hợp với trạng thái hiện tại, ví dụ hủy một phong bì đã hoàn tất hoặc tạo phiên cho người nhận đã ký
409	`not-your-turn`	Người ký gửi trước khi các nhóm chuyển tiếp trước đó xong
409	`document-mismatch`	Tài liệu đã thay đổi kể từ khi được hiển thị cho người ký (`viewedDocumentHash`)
409	`already-signed`	Địa chỉ email đã ký liên kết luôn hoạt động này
409	`in-use`	Xóa một mẫu đang được phong bì hoặc liên kết ký sử dụng
409	`no-draft`	Xuất bản một mẫu không có bản nháp
409	`idempotency-in-progress`	Một yêu cầu có cùng `Idempotency-Key` vẫn đang chạy
409	`conflict`	Các xung đột khác
410	`gone`	Một phiên ký đã được dùng hoặc đã hết hạn
413	`payload-too-large`	Tệp tải lên vượt giới hạn (25 MB đối với tệp mẫu)
415	`unsupported-media-type`	Tệp tải lên thuộc loại không được hỗ trợ
422	`validation-error`	Nội dung, query hoặc các biến không hợp lệ; xem `errors`
422	`idempotency-key-reused`	Cùng một `Idempotency-Key` được dùng với một yêu cầu khác
422	`conversion-failed`	Không thể chuyển đổi tài liệu Word
429	`rate-limited`	Quá nhiều yêu cầu; hãy chờ số giây trong `Retry-After` nếu có
500	`internal`	Lỗi không mong muốn. Có thể thử lại an toàn với cùng `Idempotency-Key`
501	`not-implemented`	Tính năng có trong schema nhưng chưa được triển khai (ví dụ mã SMS)
503	`converter-unavailable`, `billing-unavailable`	Một thành phần phụ thuộc tạm thời không khả dụng; hãy thử lại sau

Xử lý lỗi

const res = await fetch('https://api.bonafidesign.com/v1/envelopes', { method: 'POST', headers, body });
if (!res.ok) {
  const problem = await res.json(); // application/problem+json
  const slug = problem.type.split('/').pop();
  if (slug === 'validation-error') {
    for (const e of problem.errors) form.setError(e.pointer, e.message);
  } else if (slug === 'payment-required') {
    showUpgrade(problem.upgradeUrl);
  } else {
    throw new Error(`${problem.title} (${problem.requestId})`);
  }
}