Guides

Giới hạn tần suất và lỗi

Public API per-account rate limits, error response format, status codes and caching guidance.

On this page

Rate limits
Status codes
Error format
Caching

Rate limits#

Lưu ý

API công khai và MCP đã xác thực dùng chung hạn mức theo giờ cho mỗi đối tác (mặc định 20.000). Thêm hoặc xoay vòng khóa không làm tăng hạn mức này.

Khung 3,600 giây bắt đầu từ yêu cầu đầu tiên; giới hạn theo phút cũng được áp dụng. Hạn mức tính theo số lần gọi, không phải số MB truyền tải. Cài đặt vận hành có thể thay đổi hạn mức.

Lô MCP nhận tối đa 100 tin nhắn và mỗi tin nhắn được tính là một lệnh gọi. Lô vượt quá hạn mức khả dụng sẽ trả về 429 trước khi thực thi.

X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset

Các header này cho biết giới hạn theo giờ, số lần gọi còn lại và thời điểm đặt lại (giây Unix). Khi hết hạn mức theo giờ, hệ thống trả về HTTP 429 kèm Retry-After tính bằng giây. Các lần gọi bị từ chối do giới hạn theo phút không tính vào hạn mức theo giờ.

Mặc định mỗi tài khoản đối tác được gửi 600 yêu cầu mỗi phút. Nếu vượt quá, bạn sẽ nhận 429 rate_limited.

Tiền boa

Nếu nhận lỗi 429, hãy chờ một lát rồi thử lại. Nếu lặp lại cùng một tìm kiếm, lưu bộ nhớ đệm kết quả trong vài phút là cách hiệu quả nhất.

Status codes#

HTTP	Ý nghĩa
200	Thành công
400	Tham số không hợp lệ
401 invalid_api_key	Khóa bị thiếu, sai hoặc đã bị thu hồi
404	ID eSIM không xác định
429 rate_limited	Đã vượt giới hạn tần suất

Error format#

json

// 401 — missing, invalid or revoked key
{
  "error": "invalid_api_key",
  "message": "Missing or invalid API key. Create one at https://www.esimoa.com/developers/dashboard"
}

// 429 — too many requests for this key
{ "error": "rate_limited", "message": "Rate limit exceeded (600 requests per minute)." }

// 400 — invalid parameters / 404 — unknown eSIM id
{ "statusCode": 404, "message": "eSIM not found", "error": "Not Found" }

Caching#

Giá thay đổi thường xuyên — chỉ lưu bộ nhớ đệm kết quả tìm kiếm tối đa vài phút.