เริ่มต้นใช้งาน

Error Codes

Error response มีโครงสร้างเหมือนกันทุกตัว — code + message + request_id สำหรับ debug

รูปแบบ Error Response

{
  "error": "Insufficient credits for this operation",
  "code": "insufficient_credits",
  "request_id": "req_a1b2c3d4"
}

400 Bad Request

Body หรือ query parameter ไม่ผ่าน validation (ขาด field, ผิด type, รูปแบบวันที่ผิด)

→ อ่าน response body ดู field ที่ผิด — เทียบกับ schema ใน API reference

401 Unauthorized

ไม่มี Authorization header, bearer token ผิดรูปแบบ หรือ key ไม่มีในระบบ

→ เช็ก header ว่าเป็น "Authorization: Bearer <key>" เป๊ะๆ ไม่มี whitespace เกิน

403 Forbidden

API key ใช้ได้ แต่ tier ปัจจุบันไม่ครอบคลุม endpoint นี้

→ อัปเกรด tier ใน dashboard หรือใช้ endpoint ทางเลือกใน tier ที่ถูกครอบคลุม

404 Not Found

path ไม่มีอยู่ (พิมพ์ผิด) หรือ resource ที่ขอไม่พบ

→ เช็ก path กับ API reference — ผิดบ่อย: trailing slash, version prefix ผิด

422 Unprocessable Entity

request ถูก format แต่เนื้อหาไม่ผ่าน (เช่น birth_date เป็นวันในอนาคต)

→ อ่าน response body ดูกฎ business ที่ไม่ผ่าน

429 Too Many Requests

เกิน RPM หรือ RPD ของ tier ปัจจุบัน

→ ทำตาม Retry-After — backoff แบบ exponential หรืออัปเกรด tier

500 Internal Server Error

server พังโดยไม่คาดฝัน — incident หรือ edge case ที่ยังไม่จัดการ

→ ลองซ้ำหลังหน่วงสั้นๆ ถ้ายังพังให้ส่ง request_id ไป ops@astrom8.com

502 Bad Gateway

LLM upstream ตอบ output ที่ parse ไม่ได้ (ขั้นตอน interpret ของ tarot/celtic-cross)

→ ไม่ถูกตัด credit — ลองซ้ำ ระบบจะสลับโมเดลสำรองอัตโนมัติหลังช่วง circuit สั้นๆ

503 Service Unavailable

dependency ที่จำเป็นล่ม (เช่น ไม่มี LLM key สำหรับ tarot reports)

→ รอแล้วลองใหม่ — ดู status page ถ้าเหตุการณ์เป็นวงกว้าง

code	HTTP	ความหมาย
invalid_input	400	Body หรือ query ไม่ผ่าน Zod schema — response บอก path ของ field ที่ผิด
unauthorized	401	ไม่มี bearer token หรือ token ไม่ถูกต้อง
forbidden_tier	403	tier ของ API key ไม่ครอบคลุม endpoint นี้
insufficient_credits	402	quota หมดเดือนและเปิดป้องกัน overage ไว้
rate_limited	429	เกิน RPM/RPD ของ tier — มี Retry-After ให้
pdf_unavailable	503	ระบบสร้าง PDF ล่ม (เกี่ยวกับ /api/v3/reports/thai-calendar/pdf)
interpretation_unavailable	503	เส้นทาง LLM inference ที่ตั้งค่าไว้ใช้งานไม่ได้ทั้งหมด หรือยังไม่ได้ตั้งค่า — ไม่ถูกตัด credit
circuit_open	503	circuit breaker เปิดหลัง upstream พังต่อเนื่อง — auto-recover ภายในไม่กี่นาที
image_generation_failed	503	การสร้างภาพ wheel/natal upstream พัง — ไม่ถูกตัด credit