Lỗi

Mọi lỗi đều trả về cùng một cấu trúc JSON:

{
  "error": "human readable message",
  "code": "SNAKE_CASE_CODE",
  "request_id": "8f0e1c54-...",
  "retry_after": 27
}

retry_after chỉ xuất hiện trên các lỗi rate-limit và luôn tính bằng giây. request_id khớp với response header X-Request-ID — hãy đính kèm nó trong bất kỳ ticket hỗ trợ nào.

Các code

HTTP	Code	Ý nghĩa
400	`BAD_REQUEST`	Thiếu hoặc sai định dạng query parameter.
401	`MISSING_API_KEY`	Header `X-API-Key` không có.
401	`INVALID_API_KEY`	Key không được nhận diện.
401	`REVOKED_API_KEY`	Key đã bị thu hồi từ dashboard.
401	`EXPIRED_API_KEY`	Key đã vượt quá `expires_at`.
401	`UNAUTHORIZED`	Endpoint nội bộ, sai shared secret.
404	`NOT_FOUND`	Đường dẫn không khớp với route nào.
429	`RATE_LIMIT_MINUTE`	Đã cạn hạn mức theo phút.
429	`RATE_LIMIT_DAY`	Đã cạn hạn mức theo ngày.
429	`RATE_LIMIT_IP`	Rate-limit theo IP (chỉ áp dụng cho demo endpoint).
500	`INTERNAL_ERROR`	Lỗi server không mong muốn. Thử lại với backoff.

Cách xử lý được khuyến nghị

401 INVALID_API_KEY / REVOKED_API_KEY — hiển thị cho người dùng, không thử lại.
429 RATE_LIMIT_* — chờ retry_after giây rồi thử lại.
5xx — exponential backoff tối đa 3 lần thử.

Các code

Cách xử lý được khuyến nghị

On this page