Blog

รหัสสถานะ HTTP ที่ REST API ควรใช้

Ashley Innocent

Ashley Innocent

13 March 2026

รหัสสถานะ HTTP ที่ REST API ควรใช้

enterprise.banner.title

enterprise.banner.feature1

enterprise.banner.feature2

enterprise.banner.feature3

enterprise.banner.ctaB

สรุป (TL;DR)

REST API ควรใช้รหัสสถานะ HTTP อย่างถูกต้อง: 200 สำหรับ GET ที่สำเร็จ, 201 สำหรับ POST ที่สร้างทรัพยากรสำเร็จ, 204 สำหรับ DELETE ที่สำเร็จ, 400 สำหรับข้อผิดพลาดของไคลเอนต์, 401 สำหรับการยืนยันตัวตนล้มเหลว, 404 สำหรับไม่พบ และ 500 สำหรับข้อผิดพลาดของเซิร์ฟเวอร์ Modern PetstoreAPI ใช้รหัสสถานะ HTTP มาตรฐานทั้งหมดพร้อมความหมายที่เหมาะสมและการตอบสนองข้อผิดพลาดตาม RFC 9457

บทนำ

API ของคุณส่งคืน 200 OK สำหรับทุกอย่างใช่หรือไม่? สำเร็จ? 200 OK ข้อผิดพลาดในการตรวจสอบ? 200 OK พร้อมข้อความแสดงข้อผิดพลาดในเนื้อหา ไม่พบทรัพยากร? 200 OK พร้อม {"error": "not found"} การยืนยันตัวตนล้มเหลว? คุณเดาถูกแล้ว — 200 OK

นี่เป็นสิ่งที่ไม่ถูกต้อง รหัสสถานะ HTTP มีเหตุผลในการดำรงอยู่ พวกมันบอกไคลเอนต์ว่าเกิดอะไรขึ้นโดยไม่ต้องแยกวิเคราะห์เนื้อหาการตอบกลับ แคช, พร็อกซี และเครื่องมือตรวจสอบต่างพึ่งพารหัสสถานะ เมื่อคุณส่งคืน 200 สำหรับข้อผิดพลาด คุณกำลังทำลายระบบนิเวศ HTTP ทั้งหมด

Swagger Petstore เก่าเคยทำผิดพลาดเรื่องรหัสสถานะ: ส่งคืน 200 สำหรับคำขอ POST ที่ควรส่งคืน 201, ใช้ 200 สำหรับการดำเนินการ DELETE ที่ควรส่งคืน 204 และขาดรหัสข้อผิดพลาดที่สำคัญ Modern PetstoreAPI แก้ไขปัญหานี้โดยการใช้หลักการ HTTP ที่ถูกต้องในทุกเอนด์พอยต์

💡
หากคุณกำลังสร้างหรือทดสอบ REST API, Apidog ช่วยให้คุณตรวจสอบการใช้งานรหัสสถานะ, ทดสอบสถานการณ์ข้อผิดพลาด และทำให้แน่ใจว่า API ของคุณปฏิบัติตามมาตรฐาน HTTP คุณสามารถกำหนดรหัสสถานะที่คาดหวัง, เรียกใช้การทดสอบอัตโนมัติ และตรวจจับการตอบสนองที่ไม่ถูกต้องก่อนการปรับใช้
button

ในคู่มือนี้ คุณจะได้เรียนรู้ว่ารหัสสถานะ HTTP ใดบ้างที่สำคัญสำหรับ REST API, เมื่อใดควรใช้แต่ละรหัส และ Modern PetstoreAPI นำรหัสเหล่านั้นไปใช้อย่างถูกต้องได้อย่างไร

ปัญหารหัสสถานะ

API จำนวนมากมองว่ารหัสสถานะเป็นเรื่องรอง ผลที่ได้คือ: หลักการ HTTP ที่ผิดเพี้ยนและไคลเอนต์ที่สับสน

แอนตี้แพทเทิร์น "200 OK สำหรับทุกสิ่ง"

// Success
GET /users/123
200 OK
{"id": 123, "name": "John"}

// Error (but still 200!)
GET /users/999
200 OK
{"error": "User not found"}

// Validation error (still 200!)
POST /users
200 OK
{"error": "Email is required"}

ปัญหา:

ทำไมถึงเป็นเช่นนี้

นักพัฒนาส่งคืน 200 เพราะ:

  1. พวกเขาไม่รู้จักรหัสสถานะอื่น ๆ
  2. พวกเขาคิดว่ารหัสสถานะเป็นทางเลือก
  3. พวกเขาต้องการหลีกเลี่ยงการ "ทำให้" ไคลเอนต์พัง
  4. พวกเขากำลังคัดลอกตัวอย่างที่ไม่ดี (เช่น Swagger Petstore เก่า)

รหัสสถานะ HTTP ที่จำเป็นสำหรับ REST API

คุณไม่จำเป็นต้องใช้รหัสสถานะ HTTP ทั้งหมดกว่า 60 รายการ ให้เน้นที่รหัสที่จำเป็นเหล่านี้

อ้างอิงฉบับย่อ

ความสำเร็จ (2xx):

ข้อผิดพลาดของไคลเอนต์ (4xx):

ข้อผิดพลาดของเซิร์ฟเวอร์ (5xx):

รหัสความสำเร็จ (2xx)

รหัสความสำเร็จบ่งชี้ว่าคำขอสำเร็จ รหัสที่แตกต่างกันสื่อความหมายที่แตกต่างกัน

200 OK

ใช้สำหรับ: คำขอ GET, PUT, PATCH ที่สำเร็จและส่งคืนข้อมูล

GET /pets/123
200 OK
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

อย่าใช้สำหรับ: คำขอ POST ที่สร้างทรัพยากร (ใช้ 201), คำขอ DELETE (ใช้ 204)

201 Created

ใช้สำหรับ: คำขอ POST ที่สำเร็จและสร้างทรัพยากรใหม่

POST /pets
201 Created
Location: https://petstoreapi.com/pets/019b4132-70aa-764f-b315-e2803d882a24
{
  "id": "019b4132-70aa-764f-b315-e2803d882a24",
  "name": "Fluffy",
  "species": "CAT"
}

ประเด็นสำคัญ:

Modern PetstoreAPI ส่งคืน 201 สำหรับการดำเนินการ POST ทั้งหมดที่สร้างทรัพยากร

204 No Content

ใช้สำหรับ: คำขอ DELETE, PUT หรือ PATCH ที่สำเร็จโดยไม่มีเนื้อหาการตอบกลับ

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
204 No Content

ประเด็นสำคัญ:

รหัสข้อผิดพลาดของไคลเอนต์ (4xx)

รหัสข้อผิดพลาดของไคลเอนต์บ่งชี้ว่าไคลเอนต์ทำผิดพลาด คำขอไม่ควรถูกลองใหม่โดยไม่มีการแก้ไข

400 Bad Request

ใช้สำหรับ: คำขอที่ผิดรูปแบบ, JSON ไม่ถูกต้อง, ข้อมูลที่จำเป็นขาดหายไป

POST /pets
400 Bad Request
Content-Type: application/problem+json

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name is required"
    }
  ]
}

Modern PetstoreAPI ใช้รูปแบบ RFC 9457 สำหรับการตอบสนองข้อผิดพลาดทั้งหมด

401 Unauthorized

ใช้สำหรับ: ข้อมูลรับรองการยืนยันตัวตนขาดหายไปหรือไม่ถูกต้อง

GET /pets
401 Unauthorized
WWW-Authenticate: Bearer realm="PetstoreAPI"

{
  "type": "https://petstoreapi.com/errors/authentication-required",
  "title": "Authentication Required",
  "status": 401,
  "detail": "Valid authentication credentials required"
}

ประเด็นสำคัญ:

403 Forbidden

ใช้สำหรับ: ผู้ใช้ที่ยืนยันตัวตนแล้วแต่ไม่มีสิทธิ์

DELETE /pets/019b4132-70aa-764f-b315-e2803d882a24
403 Forbidden

{
  "type": "https://petstoreapi.com/errors/insufficient-permissions",
  "title": "Insufficient Permissions",
  "status": 403,
  "detail": "You don't have permission to delete this pet"
}

ความแตกต่างจาก 401:

404 Not Found

ใช้สำหรับ: ไม่พบทรัพยากร

GET /pets/nonexistent-id
404 Not Found

{
  "type": "https://petstoreapi.com/errors/not-found",
  "title": "Not Found",
  "status": 404,
  "detail": "Pet not found"
}

อย่าใช้สำหรับ: ข้อผิดพลาดในการอนุญาต (ใช้ 403), ข้อผิดพลาดในการตรวจสอบ (ใช้ 400)

409 Conflict

ใช้สำหรับ: ทรัพยากรขัดแย้งกัน เช่น ซ้ำกันหรือไม่ตรงกันของเวอร์ชัน

POST /pets
409 Conflict

{
  "type": "https://petstoreapi.com/errors/duplicate-resource",
  "title": "Duplicate Resource",
  "status": 409,
  "detail": "A pet with this microchip ID already exists"
}

422 Unprocessable Entity

ใช้สำหรับ: รูปแบบคำขอถูกต้องแต่มีข้อผิดพลาดทางความหมาย

POST /pets
422 Unprocessable Entity

{
  "type": "https://petstoreapi.com/errors/business-rule-violation",
  "title": "Business Rule Violation",
  "status": 422,
  "detail": "Cannot adopt more than 5 pets per household"
}

ความแตกต่างจาก 400:

429 Too Many Requests

ใช้สำหรับ: เกินขีดจำกัดอัตราการร้องขอ

GET /pets
429 Too Many Requests
RateLimit-Limit: 100
RateLimit-Remaining: 0
RateLimit-Reset: 1678886400

{
  "type": "https://petstoreapi.com/errors/rate-limit-exceeded",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit of 100 requests per hour exceeded"
}

Modern PetstoreAPI ใช้ เฮดเดอร์ IETF rate limit

รหัสข้อผิดพลาดของเซิร์ฟเวอร์ (5xx)

รหัสข้อผิดพลาดของเซิร์ฟเวอร์บ่งชี้ว่าเซิร์ฟเวอร์ล้มเหลว ไคลเอนต์สามารถลองร้องขอเหล่านี้ใหม่ได้

500 Internal Server Error

ใช้สำหรับ: ข้อผิดพลาดของเซิร์ฟเวอร์ที่ไม่คาดคิด

GET /pets
500 Internal Server Error

{
  "type": "https://petstoreapi.com/errors/internal-error",
  "title": "Internal Server Error",
  "status": 500,
  "detail": "An unexpected error occurred"
}

อย่ารวม: สแต็คเทรซ, รายละเอียดภายใน, ข้อผิดพลาดของฐานข้อมูลในการผลิต

503 Service Unavailable

ใช้สำหรับ: ไม่สามารถให้บริการชั่วคราว (การบำรุงรักษา, โหลดเกิน)

GET /pets
503 Service Unavailable
Retry-After: 3600

{
  "type": "https://petstoreapi.com/errors/service-unavailable",
  "title": "Service Unavailable",
  "status": 503,
  "detail": "Service temporarily unavailable for maintenance"
}

รวมเฮดเดอร์ Retry-After เพื่อบอกไคลเอนต์ว่าเมื่อใดที่พวกเขาสามารถลองใหม่ได้

Modern PetstoreAPI ใช้รหัสสถานะอย่างไร

Modern PetstoreAPI ใช้หลักการ HTTP ที่เหมาะสมในทุกเอนด์พอยต์

ตัวอย่าง: การจัดการสัตว์เลี้ยง

// List pets
GET /pets
200 OK

// Create pet
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

// Get pet
GET /pets/{id}
200 OK (found) or 404 Not Found

// Update pet
PUT /pets/{id}
200 OK (with body) or 204 No Content

// Delete pet
DELETE /pets/{id}
204 No Content (success) or 404 Not Found

การตอบสนองข้อผิดพลาด

ข้อผิดพลาดทั้งหมดใช้รูปแบบ RFC 9457:

{
  "type": "https://petstoreapi.com/errors/validation-error",
  "title": "Validation Error",
  "status": 400,
  "detail": "Request validation failed",
  "instance": "/pets",
  "invalid-params": [
    {
      "name": "name",
      "reason": "Name must be between 1 and 100 characters"
    }
  ]
}

ดู เอกสารการจัดการข้อผิดพลาดของ Modern PetstoreAPI สำหรับตัวอย่างที่สมบูรณ์

การทดสอบรหัสสถานะด้วย Apidog

Apidog ช่วยให้คุณทดสอบพฤติกรรมรหัสสถานะในทุกสถานการณ์

กำหนดรหัสสถานะที่คาดหวัง

paths:
  /pets:
    post:
      responses:
        '201':
          description: Pet created
        '400':
          description: Validation error
        '401':
          description: Authentication required
        '429':
          description: Rate limit exceeded

ทดสอบทุกสถานการณ์

สร้างกรณีทดสอบสำหรับ:

การทดสอบอัตโนมัติ

// Apidog test script
pm.test("Returns 201 for successful creation", () => {
  pm.response.to.have.status(201);
  pm.response.to.have.header("Location");
});

pm.test("Returns 400 for missing required fields", () => {
  pm.response.to.have.status(400);
  pm.expect(pm.response.json().type).to.include("validation-error");
});

ข้อผิดพลาดที่พบบ่อยที่ควรหลีกเลี่ยง

ข้อผิดพลาดที่ 1: การใช้ 200 สำหรับ POST

// Wrong
POST /pets
200 OK

// Correct
POST /pets
201 Created
Location: https://petstoreapi.com/pets/{id}

ข้อผิดพลาดที่ 2: การใช้ 200 สำหรับ DELETE

// Wrong
DELETE /pets/{id}
200 OK
{"message": "Deleted successfully"}

// Correct
DELETE /pets/{id}
204 No Content

ข้อผิดพลาดที่ 3: สับสนระหว่าง 401 และ 403

// Wrong: User is authenticated but lacks permission
401 Unauthorized

// Correct
403 Forbidden

ข้อผิดพลาดที่ 4: การใช้ 500 สำหรับข้อผิดพลาดของไคลเอนต์

// Wrong: Validation error returns 500
POST /pets
500 Internal Server Error

// Correct
POST /pets
400 Bad Request

บทสรุป

รหัสสถานะ HTTP ไม่ใช่ทางเลือก พวกมันเป็นส่วนหนึ่งของข้อกำหนด HTTP และจำเป็นสำหรับการสร้าง REST API ที่เหมาะสม

ใช้รหัสสถานะที่ถูกต้อง:

Modern PetstoreAPI แสดงให้เห็นการใช้งานรหัสสถานะที่ถูกต้องในทุกเอนด์พอยต์ ศึกษา เอกสารประกอบ REST API เพื่อดูการใช้งานที่เหมาะสม

ทดสอบรหัสสถานะของคุณด้วย Apidog เพื่อให้แน่ใจว่า API ของคุณปฏิบัติตามมาตรฐาน HTTP

คำถามที่พบบ่อย

ฉันควรใช้ 200 หรือ 204 สำหรับการ DELETE ที่สำเร็จ?

ใช้ 204 No Content ซึ่งบ่งชี้ว่าสำเร็จโดยไม่มีเนื้อหาการตอบกลับ ช่วยประหยัดแบนด์วิธ ใช้ 200 เฉพาะในกรณีที่คุณต้องการส่งคืนข้อมูลเกี่ยวกับทรัพยากรที่ถูกลบ

400 กับ 422 แตกต่างกันอย่างไร?

400 หมายถึงคำขอผิดรูปแบบ (JSON ไม่ถูกต้อง, ชนิดข้อมูลผิด) 422 หมายถึงคำขอที่จัดรูปแบบได้ดีแต่ละเมิดกฎทางธุรกิจ

ฉันควรใช้ 401 กับ 403 เมื่อใด?

401 หมายถึง "โปรดยืนยันตัวตน" (ข้อมูลรับรองขาดหายไปหรือไม่ถูกต้อง) 403 หมายถึง "คุณได้รับการยืนยันตัวตนแล้วแต่ไม่ได้รับอนุญาต" (สิทธิ์ไม่เพียงพอ)

ฉันควรส่งคืน 404 หรือ 403 สำหรับทรัพยากรที่ผู้ใช้ไม่สามารถเข้าถึงได้?

ส่งคืน 403 หากทรัพยากรมีอยู่แต่ผู้ใช้ไม่มีสิทธิ์ ส่งคืน 404 หากคุณต้องการซ่อนการมีอยู่ของทรัพยากรจากผู้ใช้ที่ไม่ได้รับอนุญาต

ฉันจะทดสอบทุกสถานการณ์รหัสสถานะได้อย่างไร?

ใช้ Apidog เพื่อสร้างกรณีทดสอบสำหรับความสำเร็จ, ข้อผิดพลาดในการตรวจสอบ, การยืนยันตัวตนล้มเหลว, ไม่พบ และข้อผิดพลาดของเซิร์ฟเวอร์ เรียกใช้การทดสอบอัตโนมัติใน CI/CD

รหัสสถานะใดสำหรับการจำกัดอัตรา?

ใช้ 429 Too Many Requests พร้อมเฮดเดอร์ RateLimit-* รวม Retry-After เพื่อบอกไคลเอนต์ว่าเมื่อใดที่พวกเขาสามารถลองใหม่ได้

ฉันควรใช้ 500 สำหรับข้อผิดพลาดของเซิร์ฟเวอร์ทั้งหมดหรือไม่?

ใช้ 500 สำหรับข้อผิดพลาดที่ไม่คาดคิด ใช้ 502 สำหรับความล้มเหลวของบริการต้นทาง, 503 สำหรับไม่สามารถให้บริการชั่วคราว และ 504 สำหรับการหมดเวลา

Modern PetstoreAPI จัดการข้อผิดพลาดอย่างไร?

ข้อผิดพลาดทั้งหมดใช้รูปแบบ RFC 9457 พร้อมรหัสสถานะที่เหมาะสม ดู เอกสารประกอบการจัดการข้อผิดพลาด สำหรับตัวอย่าง

ฝึกการออกแบบ API แบบ Design-first ใน Apidog

ค้นพบวิธีที่ง่ายขึ้นในการสร้างและใช้ API

ลงทะเบียนฟรีดาวน์โหลด
รหัสสถานะ HTTP ที่ REST API ควรใช้