Tài liệu tham khảo · Lỗi

Mã lỗi Photta API mọi loại lỗi và hướng xử lý

Tóm tắt trong một câu

Mọi lỗi của Photta API đều trả về cùng một cấu trúc: một status, một `error.type`, một message và một `request_id`. Thử lại 429 sau khoảng thời gian trong header Retry-After và 5xx với cơ chế backoff; tự sửa các lỗi 400, 401 và 402 trong mã nguồn của bạn.

Lấy API keyĐọc tài liệu
  • Lỗi: 7 loại lỗi
  • Retry-After: Retry-After: 30s
  • Giới hạn: 600 requests/min

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

Các loại lỗi

Danh sách đầy đủ được công bố trong tài liệu API.

400invalid_request_error
The request is malformed or contains invalid parameters.
401authentication_error
The API key is missing, invalid, or expired.
402insufficient_credits_error
Your account does not have enough credits.
404not_found_error
The requested resource does not exist.
409conflict_error
The request conflicts with current state — e.g. your concurrent-batch cap is reached.
429rate_limit_error
Too many requests. Slow down and retry.Retry-After: 30
500api_error
An internal server error occurred. Retry later.

Cấu trúc của một lỗi

Cùng một envelope trên mọi endpoint, bất kể lỗi gì xảy ra.

{
  "error": {
    "type": "rate_limit_error",
    "message": "Rate limit exceeded."
  },
  "request_id": "req_xxxxxxxx"
}

Xử lý lỗi

  • Tuân thủ Retry-After

    Lỗi 429 đi kèm header Retry-After. Hãy chờ đủ số giây đó, sau đó thử lại với exponential backoff — việc thử lại ngay lập tức chỉ đẩy khung thời gian tiếp theo ra xa hơn.

  • Thất bại được hoàn lại credits

    Một tác vụ tạo ảnh bị thất bại sau khi đã được tiếp nhận sẽ tự động hoàn lại credits, do đó việc thử lại sẽ không bị tính phí hai lần.

  • Cung cấp request id

    Mọi phản hồi đều chứa một `request_id`. Hãy ghi log giá trị này. Đây là cách nhanh nhất để đội ngũ hỗ trợ tìm ra một lỗi cụ thể trong hàng ngàn yêu cầu.

  • 409 là tín hiệu về hàng đợi

    Lỗi xung đột nghĩa là gói của bạn đã đạt giới hạn batch đồng thời. Hãy thực hiện polling batch đang xử lý cho đến khi hoàn tất, sau đó gửi lại — không gửi lặp liên tục.

Câu hỏi về lỗi API

Cấu trúc body của lỗi trông như thế nào?

Một đối tượng `error` gồm `type` và `message`, đi cùng `request_id`. Type có cấu trúc cố định và đọc được bằng máy; message dành cho người đọc và có thể thay đổi.

Những lỗi nào nên thử lại?

429 sau khi đã chờ số giây chỉ định trong Retry-After, và 5xx với exponential backoff. Lỗi 400, 401 hoặc 402 sẽ tiếp tục thất bại tương tự cho đến khi có thay đổi từ phía bạn.

402 có nghĩa là gì?

`insufficient_credits_error` — tài khoản không đủ credits cho lệnh gọi, hoặc cho toàn bộ phần giữ trước trong một batch. Không có gì được tạo ra và không có khoản phí nào bị trừ.

Làm thế nào để báo cáo một lỗi?

Gửi `request_id`, endpoint và thời gian. Bộ ba thông tin đó xác định chính xác lệnh gọi; không cần gửi kèm ảnh để tra cứu.

Endpoint và tài liệu tham khảo

Mọi số liệu trên trang này đều lấy từ tài liệu Photta API · đã kiểm tra

Thử nghiệm API trong năm phút

Tạo một Photta API key, dán đoạn mã cURL ở trên, và bạn sẽ nhận được bức ảnh mẫu mặc đồ đầu tiên trước khi pha xong ly cà phê.

Tạo tài khoản và lấy API keyAPI
  • 7 loại lỗi
  • Retry-After: 30s
  • 600 requests/min