Nền tảng

Mã lỗi

Định dạng lỗi JSON thống nhất của gate và DocBuilder, bảng toàn bộ mã lỗi kèm cách xử lý và khi nào nên thử lại.

Trong trang này

Định dạng lỗi thống nhất
Mã lỗi DocBuilder
Mã lỗi của gate và lớp nhúng
Mã chỉ phát ở trình duyệt
Nên thử lại khi nào

Định dạng lỗi thống nhất#

Mọi lỗi của gate (/o3o/*) và DocBuilder (/v1/*) có cùng một thân JSON. Mọi phản hồi mang header X-O3O-Request-Id trùng với request_id.

415Ví dụ: cặp định dạng không được hỗ trợ.

{
  "error": {
    "code": "unsupported_format",
    "message": "Không chuyển được từ docx sang xlsx.",
    "detail": {
      "from": "docx",
      "to": "xlsx"
    },
    "request_id": "req_0123456789abcdef"
  }
}

Trường của đối tượng <code>error</code>

codestringbắt buộc
Chuỗi ổn định để máy xử lý. Rẽ nhánh theo trường này.
messagestringbắt buộc
Câu tiếng Việt cho người đọc; có thể đổi câu chữ giữa các phiên bản, đừng phân tích.
detailobjectbắt buộcMặc định: {}
Chi tiết máy đọc được, có thể rỗng; không bao giờ chứa nội dung tài liệu.
request_idstringbắt buộc
req_ + 16 ký tự hex; gửi kèm khi báo lỗi.

Rẽ nhánh theo code, không theo message.
Gặp code lạ (bản sau có thể thêm mã mới): xử lý theo nhóm mã HTTP.
Ghi request_id vào nhật ký của bạn để đối chiếu với nhật ký máy chủ O3O.
Hai ngoại lệ không theo dạng JSON này: trang HTML chạm trần kết nối (HTTP 429) dành cho người dùng, và /o3o/auth chỉ dành cho proxy nội bộ.

Mã lỗi DocBuilder#

HTTP	`code`	Khi nào	Cách xử lý
400	`bad_request`	Thiếu tham số, JSON hỏng, `options` sai kiểu, thiếu cả `file` lẫn `url`.	Sửa yêu cầu theo `detail.errors` (`path`, `message`). Không gửi lại nguyên trạng.
401	`unauthorized`	Thiếu hoặc sai khoá. `detail.reason`: `missing`, `invalid`, `no_keys_configured`.	Kiểm header `Authorization` và danh sách khoá. `no_keys_configured`: quản trị chưa khai khoá nào.
401	`token_expired`	JWT quá hạn.	Ký JWT mới rồi gửi lại.
403	`forbidden_feature`	Endpoint hoặc tuỳ chọn không thuộc gói hiện hành. `detail.feature`, `detail.edition`.	Dùng cách khác trong gói, hoặc nâng lên bản doanh nghiệp. Không thử lại.
404	`not_found`	Không có job hoặc tệp với mã đó.	Kiểm lại mã `job_…` hoặc `file_…`.
410	`gone`	Job hoặc tệp đã hết thời gian giữ.	Gửi lại yêu cầu gốc; lần sau tải kết quả sớm hơn `result_ttl_minutes`.
413	`file_too_large`	Tệp vào hoặc tệp ra vượt `max_file_mb`. `detail.limit_mb`.	Giảm cỡ hoặc tách tệp; xem Hạn mức theo gói.
415	`unsupported_format`	Không nhận ra định dạng nguồn, hoặc cặp nguồn–đích không được hỗ trợ.	Đối chiếu `GET /v1/formats`; chỉ chuyển trong cùng một họ tài liệu. Truyền `from` khi tên tệp không có đuôi.
422	`script_invalid`	Kịch bản sai JSON Schema. `detail.errors[].path` là JSON Pointer.	Sửa đúng vị trí báo lỗi; kiểm trước bằng `o3oscript-v1.schema.json`.
422	`script_too_large`	Số đơn vị kịch bản vượt `max_script_units`. `detail.units`, `detail.limit`.	Chia kịch bản thành nhiều tài liệu nhỏ hơn.
422	`script_error`	Kịch bản hợp lệ nhưng chạy lỗi. `detail.path` chỉ tới phần tử gây lỗi.	Sửa phần tử tại `detail.path`.
422	`template_error`	Thẻ lặp không cân, hoặc thiếu trường khi `missing = "error"`. `detail.fields`.	Cân lại thẻ `{{#…}}`/`{{/…}}` trong cùng một hàng; bổ sung dữ liệu hoặc đổi `options.missing`.
422	`macro_not_allowed`	Mẫu gửi tới `POST /v1/template/render` có macro: tệp OOXML có phần `vbaProject.bin` hoặc kiểu nội dung `macroEnabled`, tệp ODF có thư mục `Basic/` hay `Scripts/`. `detail.reason`, `detail.part`; trả ngay cả khi `async = true`.	Lưu lại mẫu ở dạng không có macro (ví dụ `docm` thành `docx`) rồi gửi lại. Chuyển đổi và trích xuất vẫn nhận tệp có macro vì chúng nạp tệp ở chế độ không chạy macro.
422	`corrupt_source`	Không mở được tệp nguồn.	Kiểm tệp bằng ứng dụng văn phòng; không thử lại nguyên trạng.
422	`password_required`	Tệp có mật khẩu mà thiếu hoặc sai mật khẩu.	Truyền `options.password` (chuyển đổi) hoặc `password` (trích xuất).
422	`url_not_allowed`	URL vi phạm quy tắc chống SSRF.	Dùng URL `http`/`https` công khai, hoặc gửi tệp bằng multipart. Máy nội bộ phải được quản trị đưa vào `O3O_FETCH_ALLOW_HOSTS`.
422	`download_failed`	Không tải được URL nguồn (lỗi mạng, mã khác 200, quá giờ).	Kiểm URL từ phía máy chủ O3O; có thể thử lại sau.
429	`rate_limited`	Vượt hạn mức tần suất. `detail.window`: `minute` hoặc `day`.	Chờ đúng `Retry-After` giây rồi thử lại. Xem Hạn mức theo gói.
500	`internal`	Lỗi không lường trước.	Thử lại một lần; lặp lại thì gửi `request_id` cho quản trị.
503	`queue_full`	Hàng đợi đã đầy (`max_queued_jobs`).	Chờ `Retry-After`; giảm số yêu cầu song song.
503	`pool_unavailable`	Không còn worker nào sống.	Thử lại sau; quản trị xem nhật ký `o3o-docbuilder`.
504	`timeout`	Chế độ đồng bộ quá `sync_timeout_seconds`, hoặc job quá `job_timeout_seconds`.	Tệp nặng: dùng `async = true`. Job quá giờ: chia nhỏ việc.

Mã lỗi của gate và lớp nhúng#

Gate dùng chung ba mã chung của DocBuilder với cùng nghĩa: not_found (404), bad_request (400, hoặc giữ nguyên mã HTTP như 405 khi sai phương thức) và internal (500). Riêng WOPI host nội bộ trả not_implemented (501) cho thao tác WOPI chưa có ở v1. Các mã còn lại trong bảng là mã riêng của lớp nhúng.

HTTP	`code`	Khi nào	Cách xử lý
400	`bad_request`	Mã chung, cùng nghĩa với DocBuilder: tham số hoặc thân yêu cầu sai; phương thức không được hỗ trợ ở đường dẫn đó (giữ nguyên mã HTTP, ví dụ 405, kèm `detail.method`); thân PutFile rỗng.	Sửa yêu cầu; không gửi lại nguyên trạng.
400	`invalid_config`	Config thiếu hoặc sai trường. `detail.errors = [{path, message}]`.	Sửa config theo từng `path`.
401	`token_required`	Máy chủ yêu cầu JWT nhưng config không có.	Ký config ở máy chủ của bạn, xem Xác thực.
401	`invalid_token`	Chữ ký sai, không phải HS256, thiếu `exp`, hoặc `exp` xa quá 24 giờ.	Ký lại đúng quy tắc.
401	`token_expired`	Quá `exp`.	Ký token mới.
401	`embed_auth_not_configured`	Máy chủ chưa đặt khoá và không bật chế độ không ký.	Quản trị đặt `O3O_EMBED_JWT_SECRET`.
401	`invalid_session_token`	`Authorization` không khớp phiên.	Dùng `access_token` của đúng phiên (`api.js` tự làm).
403	`origin_not_allowed`	`Origin` không nằm trong `O3O_EMBED_ALLOWED_ORIGINS`.	Quản trị thêm origin của trang vào danh sách.
403	`invalid_signature`	Chữ ký của URL tải tệp sai.	Dùng nguyên văn URL từ callback hoặc `onSaved`, không sửa tham số.
404	`not_found`	Mã chung, cùng nghĩa với DocBuilder: đường dẫn không có, phiên hoặc tài liệu không tồn tại, hoặc lớp nhúng đang tắt.	Kiểm đường dẫn và mã phiên; kiểm `O3O_EMBED_ENABLED`.
410	`link_expired`	URL tải đã hết hạn.	Lấy URL mới qua `GET /o3o/embed/session/{session_id}` khi phiên còn.
410	`version_gone`	Phiên bản đã bị dọn (gate giữ 5 bản gần nhất cộng bản gốc).	Tải phiên bản mới hơn.
413	`file_too_large`	Vượt `O3O_EMBED_MAX_FILE_MB`.	Giảm cỡ tệp hoặc nâng giới hạn ở máy chủ.
415	`unsupported_file_type`	`fileType` ngoài danh sách được nhận.	Dùng một trong: docx, doc, odt, rtf, txt, xlsx, xls, ods, csv, pptx, ppt, odp.
422	`url_not_allowed`	`document.url` hoặc `callbackUrl` vi phạm quy tắc chống SSRF.	Dùng URL công khai, hoặc nhờ quản trị thêm máy vào `O3O_FETCH_ALLOW_HOSTS`.
422	`download_failed`	Không tải được `document.url`.	URL phải trả 200 cho máy chủ O3O.
500	`internal`	Mã chung, cùng nghĩa với DocBuilder: lỗi không lường trước trong gate.	Thử lại một lần; lặp lại thì gửi `request_id` cho quản trị.
501	`not_implemented`	Thao tác WOPI chưa có ở v1 (ví dụ `X-WOPI-Override` như `PUT_RELATIVE`, `RENAME_FILE`). Chỉ máy chủ soạn thảo gặp mã này, vì proxy không mở `/o3o/wopi/` ra ngoài.	Không cần xử lý ở phía tích hợp; tính năng tương ứng sắp có.
503	`editor_unavailable`	Không lấy được danh mục trình soạn thảo từ máy chủ soạn thảo.	Thử lại sau vài giây; kiểm `upstream.coolwsd` trong `/o3o/status`.

Mã connection_limit_reached (403) chỉ đi từ gate tới proxy nội bộ. Người dùng không nhận JSON này: qua Nextcloud họ thấy trang "Đã đạt giới hạn kết nối" (HTTP 429), còn phiên nhúng được mở ở chế độ chỉ đọc kèm sự kiện onLimitReached. Xem Kết nối được đếm thế nào.

Mã chỉ phát ở trình duyệt#

api.js phát thêm các mã dưới đây qua sự kiện onError với đối tượng {code, message, detail}.

`code`	Khi nào	Cách xử lý
`network_error`	Không gọi được máy chủ O3O.	Kiểm địa chỉ `api.js`, CORS và mạng; thử lại.
`load_failed`	Khung soạn thảo báo nạp hỏng, hoặc không có tài liệu sau 120 giây.	Kiểm tệp gốc và `O3O_ONLINE_FRAME_ANCESTORS` khi trang khác origin.
`save_failed`	Máy chủ soạn thảo báo lưu không thành công; `detail` chứa nguyên thông điệp.	Gọi `save()` lại; tài liệu vẫn nằm trong phiên.
`save_timeout`	`save()` quá 30 giây.	Thử lại; kiểm kết nối mạng.

Nên thử lại khi nào#

Nhóm	Mã	Hành động
Tạm thời	`429 rate_limited`, `503 queue_full`, `503 pool_unavailable`, `503 editor_unavailable`, `network_error`	Thử lại sau `Retry-After` (nếu có) hoặc giãn cách tăng dần.
Có thể tạm thời	`500 internal`, `504 timeout`, `422 download_failed`	Thử lại một lần; với `timeout` hãy chuyển sang `async = true`.
Sửa yêu cầu	`400`, `413`, `415`, `422 script_*`, `422 template_error`, `422 macro_not_allowed`, `422 url_not_allowed`, `422 password_required`, `422 corrupt_source`	Không gửi lại nguyên trạng.
Sửa xác thực hoặc gói	`401`, `403`	Sửa khoá, token, origin, hoặc gói.
Không còn gì để thử	`404`, `410`, `501 not_implemented`	Tạo lại job hoặc lấy URL mới; `501` là tính năng chưa có.

Báo lỗi hoặc góp ý cho trang nàyO3O Office Online · API v1 · Phiên bản trang 26.8.6