ข้อผิดพลาดและการส่งคำขอซ้ำใน API V2

ข้อผิดพลาดและรหัสสถานะ HTTP

ข้อผิดพลาดของแอปพลิเคชันใช้ application/problem+json (RFC 9457) ให้แยกกรณีตาม code และ action ที่คงที่ ไม่ใช่ตาม detail ที่เป็นข้อความสำหรับคนอ่าน ข้อผิดพลาดจากการตรวจสอบจะมีตำแหน่ง JSON Pointer ใน errors แนบ request_id เมื่อติดต่อทีมช่วยเหลือ ความล้มเหลวของพร็อกซีหรือการรับส่งข้อมูลอาจส่งคืนเนื้อหาที่ต่างออกไป จึงควรตรวจสอบ Content-Type ก่อนแยกวิเคราะห์ JSON

ตัวอย่างสังเคราะห์ของ 422 ต่อไปนี้แสดงรูปแบบอีเมลที่ไม่ถูกต้องก่อนหักเครดิต รายการข้อผิดพลาดสาธารณะแสดงทุก code สถานะ คำอธิบาย และการดำเนินการที่แนะนำ

{
  "type": "urn:genderapi:problem:validation_error",
  "title": "validation error",
  "status": 422,
  "detail": "A valid email address is required.",
  "instance": "urn:uuid:11111111-1111-4111-8111-111111111111",
  "code": "validation_error",
  "request_id": "11111111-1111-4111-8111-111111111111",
  "documentation": "https://api.genderapi.io/api/v2/errors",
  "action": "correct_request",
  "errors": [
    {
      "pointer": "/value",
      "message": "Invalid email address."
    }
  ],
  "meta": {
    "request_id": "11111111-1111-4111-8111-111111111111",
    "duration_ms": 12,
    "access": {
      "mode": "ip_trial",
      "reason": "api_key_missing"
    },
    "usage": {
      "charged_credits": 0,
      "remaining_credits": null,
      "billing_status": "not_charged",
      "resets_at": "2026-09-26T12:00:00.000Z",
      "limit": 10,
      "period_seconds": 86400
    }
  }
}

• รายการข้อผิดพลาดทั้งหมดของ V2

ฟิลด์การตอบกลับของข้อผิดพลาด

เมทาดาทาของการเข้าถึง การหักเครดิต และคำขอ

การส่งคำขอซ้ำและการหักเครดิต

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

สำหรับการตอบกลับ 429 ให้รอตาม Retry-After ก่อนส่งคำขอถัดไป สำหรับการคาดการณ์ที่ล้มเหลว ให้ตรวจสอบ code, action และ meta.usage.billing_status ก่อน หากพบ billing_reconciliation_required หรือการหักเครดิตยังไม่ยืนยัน ให้ติดต่อทีมช่วยเหลือพร้อม request_id ก่อนส่งคำขอซ้ำ

คำขอแบบกลุ่มที่สำเร็จบางส่วนอาจส่งคืน HTTP 200 ตรวจสอบทุกรายการ และส่งซ้ำเฉพาะรายการที่ล้มเหลวหลังยืนยันการหักเครดิตแล้ว หากส่งรายการที่สำเร็จซ้ำจะถูกหักเครดิตอีกครั้ง

X-Request-ID และ meta.request_id ระบุการส่ง HTTP ครั้งปัจจุบัน อ่าน /usage เพื่อดูยอดคงเหลือปัจจุบัน HEAD ไม่ได้เริ่มการคาดการณ์ที่มีการหักเครดิต และการตอบกลับของการคาดการณ์และบัญชีไม่สามารถแคชได้

ไคลเอนต์ควรรองรับฟิลด์ที่เพิ่มเข้ามาในการตอบกลับ และคงค่า null ไว้เมื่อไม่มีข้อมูล

ขีดจำกัดคำขอ

รองรับ HTTP 429 และ Retry-After แทนที่จะคาดว่าคำขอจะได้รับการยอมรับเสมอที่ระดับสูงสุดเหล่านี้ ความจุของบริการใช้ร่วมกัน ค่าที่แสดงคือค่าเริ่มต้นปัจจุบันของบริการ การตอบกลับเกี่ยวกับขีดจำกัดคำขอมี X-RateLimit-Limit, X-RateLimit-Remaining และ X-RateLimit-Reset (วินาที Unix) Retry-After คือระยะเวลารอเป็นวินาที ส่วนหัวเหล่านี้อธิบายขีดจำกัดคำขอ ไม่ใช่เครดิตคงเหลือ แม้แต่การอ่าน /usage ที่ใช้ฟรีก็ยังนับรวมในขีดจำกัดคำขอ