Lỗi API v2 và thử lại

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

Lỗi ứng dụng dùng application/problem+json (RFC 9457). Xử lý lỗi dựa trên các trường ổn định code và action, thay vì phần giải thích trong detail. Với lỗi kiểm tra đầu vào, errors chứa vị trí JSON Pointer của các trường liên quan. Cung cấp request_id khi liên hệ hỗ trợ. Lỗi kết nối hoặc proxy có thể trả về nội dung khác; hãy kiểm tra Content-Type trước khi phân tích JSON.

Ví dụ tổng hợp 422 sau đây hiển thị cú pháp email không hợp lệ trước khi thanh toán. Danh mục lỗi công khai liệt kê mọi mã, trạng thái, giải thích và hành động được đề 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 đủ

Thử lại và thanh toán

Mỗi yêu cầu dự đoán là một thao tác mới, bao gồm cả một yêu cầu giống hệt được gửi lại. Quy tắc tín dụng thông thường áp dụng cho từng yêu cầu. Không có biện pháp bảo vệ yêu cầu trùng lặp, vì vậy hãy tránh việc tự động thử lại sau khi mất kết nối hoặc kết quả không xác định.

Để có phản hồi 429, hãy đợi Retry-After trước khi gửi yêu cầu khác. Để biết lỗi dự đoán, trước tiên hãy kiểm tra code, action và meta.usage.billing_status. Đối với billing_reconciliation_required hoặc thanh toán chưa được xác nhận, hãy liên hệ với bộ phận hỗ trợ bằng request_id trước khi thử lại.

Lô thành công một phần có thể trả lại HTTP 200. Kiểm tra từng mặt hàng và chỉ gửi lại các mặt hàng không thành công sau khi thanh toán được xác nhận; các mặt hàng thành công sẽ được lập hóa đơn lại nếu được gửi lại.

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

Khách hàng nên chấp nhận các trường phản hồi bổ sung và duy trì các giá trị null khi không có thông tin.

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

Xử lý HTTP 429 và Retry-After thay vì cho rằng các yêu cầu sẽ luôn được chấp nhận ở các mức trần này. Năng lực dịch vụ được chia sẻ. Các giá trị được hiển thị là giá trị mặc định của dịch vụ hiện tại. Phản hồi giới hạn tốc độ bao gồm X-RateLimit-Limit, X-RateLimit-Remaining và X-RateLimit-Reset (giây Unix). Retry-After là độ trễ 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ả số lần đọc /usage miễn phí cũng được tính vào giới hạn tốc độ.