404 trên API có phải lúc nào cũng URL sai không?

Không chỉ URL. Có thể resource đã bị xóa, ID sai, hoặc một số API trả 404 thay vì 403 để không lộ sự tồn tại của resource. Kiểm tra path, method (GET vs POST), version prefix (/v1/), và ID trong path trước khi kết luận 'API down'.

502 và 503 khác nhau ra sao khi deploy?

502 Bad Gateway = gateway/proxy nhận phản hồi xấu từ upstream (app crash, timeout, container chưa ready). 503 Service Unavailable = dịch vụ chủ động báo tạm không phục vụ (quá tải, bảo trì). Sau deploy: 502 thường là upstream chưa lên; 503 có thể là health check hoặc maintenance mode.

HTTP status code 4xx/5xx cheat sheet |

Kết luận

Quy tắc một câu: 4xx → sửa request của bạn (URL, auth, body, quyền). 5xx → đừng đoán client — thu thập bằng chứng rồi kiểm tra server/log/upstream. Junior API và freelance support nhớ thêm: đọc body lỗi trước khi đổi code lung tung, và phân biệt 401 vs 403 để khỏi mất nửa buổi.

Khi khách nhắn “API lỗi rồi”, thường họ chỉ gửi screenshot chữ đỏ hoặc "Internal Server Error". Bạn cần trả lời trong vài phút: lỗi nằm ở request, token, hay server vừa deploy. Bài này là cheat sheet 4xx/5xx thực chiến — không liệt kê hết RFC, mà tập trung mã hay gặp khi gọi REST API và hỗ trợ khách hàng.

Ai nên bookmark bài này

Junior backend/frontend lần đầu đọc Network tab
Freelance nhận ticket “API không chạy” từ khách SME / agency
QA / support cần phân loại lỗi trước khi escalate

Bạn sẽ có: quy tắc phân nhánh, bảng mã hay gặp, checklist 3 phút, case study freelance, và FAQ theo câu hỏi search.

Quy tắc phân nhánh nhanh

Nhóm	Ý nghĩa	Việc làm ngay
2xx	Thành công	Kiểm tra body có đúng kỳ vọng không (đôi khi 200 nhưng data rỗng)
4xx	Client/request	Sửa URL, method, header, query, body, quyền
5xx	Server/upstream	Không “sửa frontend cho xong” — lấy log, request ID, thời điểm

Nhớ để debug nhanh

4xx → bạn (hoặc app của bạn) đang gửi sai hoặc thiếu quyền
5xx → server, gateway, DB, hoặc service phía sau đang lỗi

Tần suất gặp trong thực tế (ước lượng)

200

404

500

401

400

403

Freelance thường gặp 401/403 (khách đưa sai key), 404 (sai môi trường staging/prod), 502 (deploy chưa ổn định) nhiều hơn lý thuyết sách giáo khoa.

Bảng mã hay gặp (bấm xem nhanh)

Checklist debug 3 phút (Network tab)

Mở DevTools → Network, tái hiện thao tác lỗi, click đúng request (đừng nhìn request khác).

Ghi status code + URL + method. Mở Response/Preview: message, errors[], requestId.

Nếu 4xx: so Request Headers (Authorization) và Payload với tài liệu API / Postman collection của khách.

Nếu 5xx: lưu timestamp UTC, môi trường (staging/prod), screenshot + body (che PII), escalate kèm bằng chứng.

Công cụ hỗ trợ khi body khó đọc

Tình huống	Việc nên làm
Response JSON một dòng, khó đọc field lỗi	Dán vào [JSON formatter](/vi/tools/json-formatter/) để xem message/errors rõ ràng
401 nghi token hết hạn hoặc sai aud	Decode JWT bằng [JWT decode](/vi/tools/jwt-decode/) — xem exp, iss, aud trước khi xin key mới
400 vì payload gửi lệch schema	Format Request Payload, đối chiếu required fields trong docs

🧪 Format JSON response lỗi

Dán body API lỗi để đọc message / errors[] nhanh hơn screenshot chữ đỏ

Thử

4xx sâu: lỗi hay gặp khi gọi API

400 — Bad Request

Triệu chứng: Validate fail ngay từ gateway hoặc framework.

Checklist:

JSON có trailing comma / quote lệch không?
Content-Type có đúng application/json không?
Query page=abc trong khi API cần số?

Ví dụ body thường gặp:

{
  "statusCode": 400,
  "message": ["email must be an email", "password should not be empty"],
  "error": "Bad Request"
}

Sửa field được liệt kê — đừng restart server.

401 vs 403 — đừng nhầm khi support khách

	401 Unauthorized	403 Forbidden
Ý nghĩa	Chưa chứng minh danh tính / chứng chỉ không hợp lệ	Đã biết bạn là ai, nhưng không được phép
Việc làm	Gắn/renew token, kiểm tra `Authorization`, clock skew	Kiểm tra role, tenant, ownership resource
Câu hỏi gửi khách	”Key/token còn hạn và đúng môi trường chưa?"	"User này có quyền trên resource X không?”

Freelance hay nhận API key staging rồi gọi prod → toàn 401. Hoặc user staff gọi endpoint admin → 403. Hai ticket khác hẳn cách xử lý.

404 — không phải lúc nào cũng “API chết”

Trước khi bảo khách “server down”:

Path có /api/v1/ không? Có thiếu trailing slash policy không?
Method đúng chưa? (GET trên route chỉ nhận POST → đôi khi 404/405)
ID trong path có phải của môi trường đó không?
Một số API bảo mật trả 404 thay 403 để không lộ resource tồn tại

422 — validation nghiệp vụ

Khác 400: request “đúng hình dạng” nhưng rule domain từ chối — ví dụ đăng ký email đã tồn tại, số lượng âm, trạng thái đơn hàng không cho hủy.

Khi viết client: map errors theo field để hiện dưới input, đừng chỉ alert(response.status).

429 — rate limit

Nếu script sync hoặc retry loop không có backoff, bạn tự tạo 429. Đọc header Retry-After, exponential backoff + jitter. Báo khách nếu họ đang poll mỗi 200ms.

5xx sâu: khi nào escalate, khi nào đợi

500 — Internal Server Error

Đừng: đổi CORS trên frontend rồi bảo “đã fix”.

Hãy gửi cho backend / khách (template ngắn):

Môi trường: staging
Thời điểm (UTC): 2026-07-19T08:12:00Z
Method + URL: POST /api/v1/orders
Status: 500
Request-Id: (nếu có)
Body lỗi (đã che PII): ...
Bước tái hiện: ...

Thiếu request ID khiến backend mất thời gian tìm log — đây là giá trị freelance mang lại ngay từ ticket đầu tiên.

502 — Bad Gateway

Thường gặp khi:

Container/app chưa listen kịp sau deploy
Nginx/Caddy timeout tới upstream
Upstream trả response không hợp lệ / connection reset

Gợi ý: đợi health check xanh, xem log reverse proxy, thử lại sau 1–2 phút — không phải lúc rewrite URL trên client.

503 — Service Unavailable

Bảo trì có chủ đích hoặc quá tải. Nếu có Retry-After, tôn trọng. Circuit breaker phía client tốt hơn spam refresh.

Case study freelance

Network: GET /orders/123 → 403
JWT decode: role: "viewer", endpoint cần role: "ops"
Kết luận: không phải bug login — thiếu quyền. Nhầm thành 401 sẽ khiến bạn đổi token cả buổi.

Case 2: Sau khi khách “vừa deploy”, toàn bộ API đỏ

Status: 502, body HTML của Nginx
App log: process chưa bind port
Kết luận: upstream chưa sẵn sàng. Client đúng; escalate DevOps/deploy, không sửa axios interceptor.

Case 3: Form tạo user luôn “lỗi”

Status: 422, message email already exists
Kết luận: không phải 500. Hiện lỗi dưới field email; đề xuất khách kiểm tra data mẫu trùng.

Playbook trả lời khách (copy nhanh)

Status	Câu trả lời gợi ý
400/422	”Request chưa đúng schema — mình gửi field lỗi cụ thể, anh/chị sửa payload giúp.”
401	”Token/key chưa hợp lệ hoặc hết hạn — kiểm tra môi trường staging/prod và giờ hết hạn.”
403	”Tài khoản đã login nhưng thiếu quyền trên resource này.”
404	”Endpoint hoặc ID không khớp môi trường — mình đối chiếu path với docs.”
429	”Đang bị rate limit — giảm tần suất gọi / thêm backoff.”
5xx	”Lỗi server/upstream — mình gửi requestId + thời điểm để team xem log.”

Câu hỏi thường gặp

401 và 403 khác nhau thế nào?
401 = chưa auth / token sai. 403 = đã auth nhưng thiếu quyền. Sửa sai loại = mất thời gian.

Gặp 500 thì client có sửa được không?
Thường không. Thu thập bằng chứng và escalate. Chỉ retry có kiểm soát với 503/tạm thời.

400 và 422 dùng khi nào?
400: sai dạng/cú pháp. 422: đúng dạng nhưng rule nghiệp vụ từ chối. Đọc docs team để biết convention.

404 trên API có phải URL sai không?
Không chỉ URL — ID sai, resource đã xóa, hoặc API cố tình ẩn resource. Kiểm tra method và version path.

502 và 503 khác nhau khi deploy?
502: gateway nhận phản hồi xấu từ upstream. 503: dịch vụ báo tạm không phục vụ. Sau deploy, 502 hay nghĩa là app chưa ready.

Liên kết hữu ích khi debug

JSON formatter — đọc body lỗi
JWT decode — kiểm tra token khi 401
Danh sách công cụ

Giữ cheat sheet này cạnh tab Network: nhìn status → chọn nhánh 4xx/5xx → hỏi đúng câu → gửi đúng bằng chứng. Đó là cách junior và freelance trông “có hệ thống” trước khách mà không cần thuộc hết RFC.

Công cụ