Lỗi và thử lại trong API V2

Lỗi và mã trạng thái HTTP

Lỗi ứng dụng dùng application/problem+json (RFC 9457). Hãy xử lý theo các trường ổn định code và action, không theo nội dung detail dành cho người đọc. Lỗi xác thực dữ liệu có vị trí JSON Pointer trong errors. Gửi kèm request_id khi liên hệ bộ phận hỗ trợ. Lỗi proxy hoặc lỗi truyền tải có thể trả về nội dung khác, vì vậy hãy kiểm tra Content-Type trước khi phân tích JSON.

Ví dụ 422 mô phỏng sau đây cho thấy cú pháp email không hợp lệ được phát hiện trước khi tính phí. Danh mục lỗi công khai liệt kê mọi mã lỗi, trạng thái, giải thích và hành động đề xuất.

{
  "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
    }
  }
}

• Danh mục lỗi V2 đầy đủ

Trường phản hồi lỗi

Siêu dữ liệu về truy cập, tính phí và yêu cầu

Thử lại và tính phí

Mỗi yêu cầu dự đoán là một thao tác mới, kể cả khi gửi lại một yêu cầu giống hệt. Quy tắc tín dụng thông thường áp dụng cho từng yêu cầu. Không có cơ chế chống yêu cầu trùng lặp, vì vậy hãy tránh tự động thử lại sau khi mất kết nối hoặc khi chưa rõ kết quả.

Với phản hồi 429, hãy chờ theo Retry-After trước khi gửi yêu cầu khác. Với dự đoán thất bại, trước tiên hãy kiểm tra code, action và meta.usage.billing_status. Với billing_reconciliation_required hoặc việc tính phí chưa được xác nhận, hãy liên hệ bộ phận hỗ trợ kèm request_id trước khi thử lại.

Một lô thành công một phần có thể trả về HTTP 200. Kiểm tra từng mục và chỉ gửi lại các mục thất bại sau khi việc tính phí đã được xác nhận; nếu gửi lại, các mục thành công sẽ bị tính phí lần nữa.

X-Request-ID và meta.request_id xác định lần gửi HTTP hiện tại. Đọc /usage để biết số dư hiện tại. HEAD không bắt đầu dự đoán bị tính phí. Phản hồi dự đoán và phản hồi tài khoản không được lưu vào bộ nhớ đệm.

Client cần chấp nhận các trường phản hồi được bổ sung thêm và giữ nguyên giá trị null khi không có thông tin.

Giới hạn yêu cầu

Hãy xử lý HTTP 429 và Retry-After thay vì cho rằng yêu cầu luôn được chấp nhận ở các mức tối đa này. Năng lực của dịch vụ được dùng chung. Các giá trị hiển thị là mặc định hiện tại của dịch vụ. Phản hồi khi vượt giới hạn tần suất có X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset (giây Unix). Retry-After là thời gian chờ tính bằng giây. Các tiêu đề này mô tả giới hạn yêu cầu, không phải số tín dụng còn lại. Ngay cả lần đọc /usage miễn phí cũng được tính vào giới hạn tần suất.