Errors
Format response, seluruh status code yang dikembalikan API, dan tindakan untuk masing-masing.
Response berhasil
Setiap response yang berhasil memakai format yang sama:
{
"status": 200,
"message": "Success",
"data": {}
}data berisi payload-nya — sebuah objek untuk satu resource, atau array untuk daftar. Endpoint
berhalaman menambahkan objek pagination:
{
"status": 200,
"message": "Success",
"data": [],
"pagination": { "total": 42, "nextPage": 2, "limit": 20, "currentPage": 1, "totalPage": 3 }
}nextPage tidak ada di halaman terakhir. Pakai keberadaannya, bukan hitungan manual atas total,
untuk menentukan apakah harus lanjut.
Response gagal
Error memakai bentuk yang berbeda. Periksa HTTP status lebih dulu; jangan mengurai data dari
sebuah error.
{
"error": {
"statusCode": 422,
"timestamp": "2026-07-03T06:00:00.000Z",
"message": "input.prompt is required",
"details": {
"errorName": "UnprocessableEntityException"
}
}
}message adalah alasan yang bisa dibaca manusia. details.errorName cukup stabil untuk dijadikan
percabangan saat Anda perlu membedakan kasus secara programatis.
Status code
| Kode | Arti | Yang harus dilakukan |
|---|---|---|
400 | Permintaan salah bentuk | Perbaiki permintaannya. Mengulang tidak menolong |
401 | Key tidak ada, tidak dikenal, atau dicabut | Periksa header x-mager-api-key. Lihat Authentication |
403 | Tidak diizinkan | Akun belum disetujui, scope kurang, atau IP tidak ada di allowlist |
404 | Tidak ditemukan | Slug model, template, atau task tidak dikenal — atau task milik akun lain |
422 | Validasi gagal | Bandingkan input Anda dengan input_schema milik model |
429 | Rate limit terlampaui | Lakukan backoff. Lihat Rate limits |
500 | Ada yang rusak di sisi kami | Coba lagi dengan backoff. Kalau terus terjadi, laporkan |
Error mana yang layak diulang
Ulangi 429 dan 500, dengan exponential backoff dan jitter.
Jangan ulangi 400, 401, 403, 404, atau 422. Tidak ada yang berbeda pada percobaan
berikutnya, dan untuk 429 loop yang rapat justru memperburuk keadaan.
Task yang gagal bukan HTTP error
Task yang gagal tetap mengembalikan 200. Kegagalannya ada di dalam body:
{
"status": 200,
"data": {
"task_id": "cmagr01hxyz123",
"status": "failed",
"error": "Model returned no output",
"result": []
}
}Periksa data.status, bukan hanya HTTP status. 200 berarti Mager menjawab pertanyaan Anda; itu
tidak berarti generasinya berhasil.