Lỗi & cấu trúc phản hồi

Mọi phản hồi — thành công hay thất bại — đều sử dụng chung một cấu trúc JSON envelope, do đó client chỉ cần một luồng xử lý duy nhất để kiểm tra thành công hay thất bại.

Phản hồi thành công

{
  "success": true,
  "data": { "…": "…" },
  "meta": {
    "request_id": "0198f3a2-…",
    "units_charged": 1,
    "pagination": { "next_cursor": "…", "has_more": true },
    "freshness": { "corpus_last_event_at": "2026-08-01T04:12:09Z" }
  }
}

pagination và freshness chỉ xuất hiện khi phù hợp với endpoint tương ứng.

Phản hồi lỗi

{
  "success": false,
  "error": {
    "code": "quota_exceeded",
    "message": "Monthly quota of 500 units used.",
    "details": { "period_end": "2026-08-31", "upgrade": "https://crawlpipe.com/pricing" }
  },
  "meta": { "request_id": "…" }
}

Hãy kiểm tra success trước — không bao giờ suy đoán lỗi chỉ dựa vào HTTP status, và không bao giờ đọc error.message để xử lý logic (nó dành cho người đọc; hãy rẽ nhánh bằng error.code).

Mã lỗi (Error codes)

HTTP	Mã lỗi	Trường hợp xảy ra
400	`validation_error`	Tham số không hợp lệ — xem `details.fields`
401	`invalid_key`	Khóa API thiếu, không tồn tại hoặc đã bị thu hồi
402	`payment_required`	Endpoint x402 chưa thanh toán, hoặc đăng ký quá hạn
403	`feature_not_in_plan`	Ví dụ: tìm kiếm ngữ nghĩa ở gói Miễn phí — xem `details.required_plan`
403	`insufficient_scope`	Khóa thiếu quyền yêu cầu — xem `details.required_scope`
404	`not_found`	Không tìm thấy tài nguyên
409	`idempotency_conflict`	Trùng `Idempotency-Key` nhưng nội dung yêu cầu khác nhau
422	`unprocessable`	Ví dụ: ngày `at=` trước khi văn bản tồn tại
429	`rate_limited`	Vượt giới hạn số yêu cầu/phút — xem header `Retry-After`
429	`quota_exceeded`	Hết hạn mức đơn vị theo tháng
429	`spending_cap_reached`	Vượt hạn mức chi tiêu của tổ chức
500	`internal_error`	Lỗi máy chủ không mong muốn

Header trên mọi phản hồi

X-Request-Id, X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix timestamp). Các yêu cầu tính phí thành công sẽ có thêm X-CrawlPipe-Units-Charged và X-CrawlPipe-Units-Remaining — xem thêm Đo lường & idempotency.