Mã lỗi API
Tra cứu theo đúng thông đi ệp server trả về. Mọi lỗi đều có dạng {"error": "<thông điệp>"} kèm mã HTTP — trang này nói mỗi thông điệp thật sự nghĩa là gì và làm gì tiếp.
Đối tượng: người gọi API và người trực sự cố. Lỗi ở giao diện (không phải API) sắp theo triệu chứng ở Xử lý sự cố. Ma trận quyền: Phân quyền Board.
Đọc mã lỗi trong 10 giây
| Mã | Nghĩa chung | Sửa ở đâu |
|---|---|---|
400 | Dữ liệu bạn gửi sai | Sửa request |
401 | Chưa xác định được bạn là ai | Lớp đăng nhập / header Authorization |
403 | Biết bạn là ai, nhưng không đủ quyền | Nhờ cấp quyền — không có đường vòng |
409 | Trạng thái hiện tại không cho phép hành động này | Đổi trạng thái trước, hoặc chấp nhận |
429 | Gửi quá nhanh | Đợi vài giây rồi thử lại |
500 | Lỗi phía server | Xem log, gọi sysadmin |
503 | Một thành phần phụ thuộc đang vắng | Kiểm Arkon / storage |
400 — dữ liệu gửi sai
Trường bắt buộc và kiểu dữ liệu
| Thông điệp | Nguyên nhân | Xử lý |
|---|---|---|
title is required and must be a non-empty string | Thiếu tiêu đề | Điền title |
projectId is invalid | Space không tồn tại | Kiểm lại spaceId |
description must be at most <N> characters | Mô tả quá dài | Cắt bớt, đưa phần chi tiết vào Wiki |
invalid columnId: must be one of backlog, in-progress, review, done | Sai tên cột | Dùng đúng 4 giá trị |
invalid priority: must be one of low, medium, high, critical | Sai mức ưu tiên | — |
invalid agentStatus: must be one of idle, planning, executing, complete, failed | Sai trạng thái agent | — |
invalid agentType / agent must be a supported agent type | Agent CLI không nằm trong danh sách hỗ trợ | GET /api/agents xem server đang có gì |
linkType must be one of: … | Sai loại liên kết | Dùng blocks cho quan hệ chặn |
mergeStrategy must be one of merge-local, create-pr, manual | Sai chiến lược hợp nhất | — |
Git và đường dẫn
| Thông điệp | Nguyên nhân | Xử lý |
|---|---|---|
repoPath must be an absolute path (e.g. ~/projects/my-app …) | Nhập đường dẫn tương đối | Nhập tuyệt đối; ~ được chấp nhận |
repoPath is locked by the task project | Space khoá đường dẫn repo cho mọi task | Sửa ở cấp Space, không sửa từng task |
baseBranch is not a valid git ref · branchName contains invalid characters | Tên nhánh không hợp lệ | Đặt tên theo quy tắc git ref |
cloneRoot must be an absolute path | — | — |
Quan hệ giữa task
| Thông điệp | Nguyên nhân | Xử lý |
|---|---|---|
Cannot link a work item to itself · a task cannot be related to itself | Tự trỏ vào chính nó | — |
Cross-project linking is not allowed. Both tasks must belong to the same project. | Liên kết task khác Space | Chuyển task về cùng Space trước |
Cannot move from <cột-cũ> to <cột-mới> | Nhảy cột sai thứ tự | Cột đi backlog → in-progress → review → done; review còn quay về in-progress được |
Task cannot move to done: Human approval is required for this Space. | Space bật Human Gate | Đi qua bước Approve, không có bypass |
Cannot run task: blocked by unresolved tasks: […] | Blocker chưa done | Xong blocker rồi chạy lại — Dependency gating |
can only archive completed or failed tasks | Archive task đang chạy | Dừng agent trước |
Group và batch
| Thông điệp | Nguyên nhân |
|---|---|
children must be an array with at least <N> items · children must have at most <N> items | Số task con ngoài khoảng cho phép |
maxConcurrency must be an integer between 1 and <số task con> | Mức song song lớn hơn số task trong Group |
batch limit is 50 tasks | POST /api/tasks/batch quá 50 task |
Đính kèm
| Thông điệp | Giới hạn thật |
|---|---|
File too large. Maximum size: 10MB | 10 MB mỗi file |
Maximum 10 attachments per task · Too many files. Maximum <N> more allowed | 10 file mỗi task |
No image files provided · file is required | Request không kèm file |
Unsupported file type: <mime>. Allowed: … | Chỉ PNG, JPEG, GIF, WebP, SVG |
401 — chưa xác định được danh tính
| Thông điệp | Nguyên nhân | Xử lý |
|---|---|---|
unauthorized | Triển khai có đặt API_KEY nhưng request thiếu hoặc sai Authorization: Bearer <token>; hoặc JWT của lớp biên không hợp lệ | Gửi đúng token. Ở dev, gọi qua cổng published không phải loopback — dùng AGENTBOARD_DEV_IDENTITY=1 + header giả lập |
GET /api/health là endpoint công khai duy nhất, không cần auth — dùng cho script giám sát.
403 — không đủ quyền (fail-closed)
| Thông điệp | Nguyên nhân | Xử lý |
|---|---|---|
Forbidden: you are not a member of Space "<id>". | Chưa có membership. Chưa được cấp thì mặc định cấm | Nhờ owner cấp quyền, hoặc dùng AGENTBOARD_BOOTSTRAP_OWNERS lần đầu |
Forbidden: this action requires the "<role>" role in Space "<id>" (you have "<role>"). | Đúng Space, sai vai trò | Nhờ nâng vai trò nếu bạn thực sự là người làm việc đó |
Forbidden: this action requires an authenticated human actor. | Human Gate — service token phân giải về system | Không có scope nào vượt được. Chuyển bước này cho người thật |
Forbidden: route is not declared in the authorization registry. | Route mới chưa khai báo luật quyền — fail-closed theo thiết kế | Lỗi lập trình: khai báo route trong registry |
Task/Draft/Source/Branch does not belong to this Space | Tài nguyên thuộc Space khác | Kiểm lại spaceId |
forbidden | Lớp auth từ chối sớm | Kiểm chuỗi danh tính ở proxy |
Không có đường vòng cho 403 của Human Gate
Không có biến môi trường, header hay scope nào cho phép agent, service token hay CI approve thay người. Gặp 403 ở đây là hệ thống đang làm đúng việc của nó.
404 — không tìm thấy
| Thông điệp | Nguyên nhân | Xử lý |
|---|---|---|
task not found · group not found · project not found | Sai id, hoặc tài nguyên đã bị xoá | Kiểm lại id. Task đã archive vẫn tồn tại — bật Show Archived để thấy |
409 — trạng thái không cho phép
| Thông điệp | Nguyên nhân | Xử lý |
|---|---|---|
agent already running for this task | Mỗi task một agent tại một thời điểm | Đợi, hoặc POST /:id/stop |
agent is already running for this task; use the message endpoint | Muốn bổ sung yêu cầu giữa chừng | POST /api/tasks/:id/message |
no running agent for this task | Dừng hoặc nhắn khi không có gì đang chạy | Kiểm GET /:id/status |
run already claimed | Bấm Run dồn hai lần | Đợi vài giây rồi kiểm status |
task is no longer eligible to start | Trạng thái đã đổi giữa lúc gửi request | Tải lại rồi thao tác lại |
agent <tên> is not ready | CLI chưa sẵn sàng trên server | GET /api/agents; production build từ Dockerfile.agents |
group is already running | Group đang chạy | Dừng Group trước |
project must have a repository path before coding work can start | Space chưa gắn repo | Đặt repoPath cho Space |
repoPath cannot be changed after tasks or groups exist | Đổi repo sau khi đã có việc | Tạo Space mới cho repo mới |
cannot remove the last owner of a Space | Chống tự khoá | Cấp owner cho người khác trước |
the default project cannot be deleted · project cannot be deleted | Space mặc định hoặc còn dữ liệu | — |
a template with that name already exists · Agent profile with name <tên> already exists | Trùng tên | Đổi tên |
only failed or timed-out orchestrations can be retried | Retry sai lúc | — |
idempotency key was already used for a different orchestration request | Dùng lại Idempotency-Key cho request khác | Sinh key mới |
429 — gửi quá nhanh
| Thông điệp | Xử lý |
|---|---|
too many requests, try again shortly · Rate limited — wait a few seconds | Đợi vài giây. Script tự động nên có backoff; đừng retry ngay lập tức vì sẽ kéo dài thời gian bị chặn |
500 / 503 — lỗi phía server
| Thông điệp | Nguyên nhân hay gặp | Xử lý |
|---|---|---|
Failed to apply plan: <chi tiết> | Plan có vòng phụ thuộc hoặc tham chiếu task không tồn tại | Sửa trong trình soạn plan rồi apply lại |
<X> repository not configured | Thành phần lưu trữ chưa được nối lúc khởi động | Lỗi cấu hình server — gọi sysadmin |
create/execution/retry attempt references a missing task | Task bị xoá giữa chừng | Tải lại danh sách |
failed to update/archive/unarchive task | Lỗi ghi database | Xem log server |
Wiki space not linked or offline (400) · Task ⇄ wiki link storage is unavailable (503) | Arkon vắng mặt hoặc Space chưa nối Wiki | Suy biến mềm Arkon |
Failed to approve draft: … (502) | Arkon từ chối quyền — đây là cổng của Arkon, không phải của Board | Kiểm vai tr ò Arkon + đợi một nhịp reconciler. Không đặt role='admin' trong Arkon để chữa: làm vỡ lọc department, mở Wiki mọi Space. Xem Phân quyền Arkon |
Tạo Space trả 500 ở môi trường dev
Gần như luôn là lệch ARKON_SSO_SHARED_SECRET ↔ SSO_SHARED_SECRET: host gọi qua
cổng published thì Docker NAT, Arkon không thấy đó là loopback nên provisioning nhận
403 và Board trả 500. Chạy lại ./scripts/dev.sh deps up để nó ghi đúng giá trị.
Đi tiếp: API hay dùng · Phân quyền Board · Máy trạng thái task · Xử lý sự cố