Error code

Mọi lỗi trả ProblemDetails (RFC 7807): title, status, detail, traceId; 422 kèm errors.

ProblemDetails

{
  "title": "Forbidden",
  "status": 403,
  "detail": "insufficient_scope: cần gis.parcels.view",
  "traceId": "req_b9a0…"
}

Mã	Nguyên nhân	Sửa
`400 invalid_request`	Thiếu tham số bắt buộc (vd lấy token thiếu client_secret).	Đọc trường detail.
`400 invalid_grant`	code sai / hết hạn (60 giây) / đã dùng, hoặc redirect_uri không khớp lúc cài.	Cho trại cài lại để nhận code mới; dùng code ngay.
`401 invalid_client`	App ID / App Secret sai, secret cũ đã quá 24 giờ, hoặc app bị tạm dừng.	Kiểm secret ở App settings › App Secret.
`401 token_revoked`	Trại gỡ app / đổi scope, app bị xoá hoặc tạm dừng — token cũ chết ngay.	Xin token mới.
`401`	Khoá / token sai, hết hạn, đã thu hồi.	Tạo lại hoặc Generate Access Token.
`403 access_denied`	Trại chưa cài app (hoặc đã gỡ).	Gửi liên kết cài.
`403 insufficient_scope`	Token thiếu scope cho lệnh này.	Thêm ở Use cases; trại đồng ý lại.
`403 workspace.developer_sandbox_outbound_blocked`	Developer workspace không gửi được ra ngoài (Zalo OA, thư, hộp thư trại, công khai camera).	Bình thường — thử trên trại thật nếu cần.
`404`	Không có dữ liệu, hoặc thuộc trại khác.	Kiểm id.
`409`	Trùng / sai trạng thái (vd mời trùng thành viên, báo cáo app lần hai trong 7 ngày).	Đọc detail.
`422`	Request body không hợp lệ — trường errors liệt kê từng lỗi.	JSON snake_case; mảng rỗng gửi [].
`429`	Vượt 600 lượt/phút (app × trại / khoá) hoặc 10 lượt/phút/IP cho /oauth/token.	Đợi Retry-After giây.
`5xx`	Lỗi máy chủ NextFarm.	Retry có lùi dần; gửi traceId (X-Correlation-ID) cho support.

Gỡ lỗi nhanh: API Explorer · Token Debugger · API Logs của app.