VẬN HÀNH API

Lỗi, retry, giới hạn tốc độ và timeout

Lỗi máy đọc có type ổn định, hướng khắc phục và hành vi retry rõ ràng.

Chi tiết lỗi

{
  "type": "https://quantumsafe.mobile-id.vn/problems/signing-profile-not-allowed",
  "title": "Signing profile is not allowed",
  "status": 422,
  "detail": "The requested profile is not approved for this tenant and CA route.",
  "instance": "/v1/signing-requests/sr_...",
  "correlationId": "...",
  "retryable": false
}

Header vận hành

Header	Mục đích
Retry-After	Hướng dẫn polling/rate-limit/backpressure
X-RateLimit-Limit	Giới hạn yêu cầu trong window
X-RateLimit-Remaining	Số yêu cầu còn lại
X-RateLimit-Reset	Thời điểm reset window
ETag / If-Match	Optimistic concurrency cho tài nguyên có thể thay đổi
Location	URI tài nguyên được tạo/bất đồng bộ

Chính sách retry

Nhóm	Retry?	Hành vi client
401/403 auth or scope	Không tự động retry	Làm mới credential hoặc sửa authorization
409 idempotency/state conflict	Có điều kiện	Đọc tài nguyên và đối soát trạng thái
422 policy/validation	Không	Sửa request/profile
429 rate limit	Có	Tuân theo Retry-After
502/503 provider unavailable	Có điều kiện	Backoff; không lặp lại thao tác được bảo vệ
504 timeout	Đọc trước khi retry	Giải quyết tài nguyên bằng idempotency key/correlation