ข้อผิดพลาด API v2 และลองใหม่

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

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

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

{
  "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 ฟรีก็ยังนับรวมในขีดจำกัดอัตรา