Penanganan Error

Error Handling

AgenWebsite Rate API tidak pernah membalas 200 kosong secara diam-diam. Setiap kegagalan mengembalikan kode status HTTP yang sesuai plus sebuah error envelope JSON yang konsisten, sehingga integrasi Anda dapat menangani setiap kasus secara deterministik.

Envelope error

Semua respons error memiliki struktur berikut. Field field hanya muncul pada error validasi untuk menandai parameter yang bermasalah, dan request_id selalu ada untuk keperluan pelacakan/dukungan.

Struktur error envelope

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Parameter 'weight' wajib diisi.",
    "field": "weight",
    "request_id": "req_1a2b3c"
  }
}

Tabel kode error

Berikut seluruh kode error yang mungkin dikembalikan API v1 beserta situasi pemicunya:

Contoh respons per kasus

400 — validation_error. Body salah, mis. weight hilang atau kedua identitas pihak diberikan sekaligus:

400 Bad Request

{
  "success": false,
  "error": {
    "code": "validation_error",
    "message": "Gunakan salah satu: postal_code ATAU subdistrict_id, tidak keduanya.",
    "field": "destination",
    "request_id": "req_44a0f2"
  }
}

404 — destination_not_found. Kode pos atau kecamatan tujuan tidak ditemukan di data master:

404 Not Found

{
  "success": false,
  "error": {
    "code": "destination_not_found",
    "message": "Lokasi tujuan tidak ditemukan. Cek kembali kode pos atau gunakan /v1/locations/search.",
    "request_id": "req_77c2b9"
  }
}

422 — unsupported_courier. Anda meminta kurir di luar lima yang didukung:

422 Unprocessable Entity

{
  "success": false,
  "error": {
    "code": "unsupported_courier",
    "message": "Kurir 'jne' tidak didukung. Pilihan valid: jnt, lion, sap, spx, jtc.",
    "field": "couriers",
    "request_id": "req_0b91de"
  }
}

502 — courier_upstream_error. Semua kurir gagal di penyedia hulu. Bila hanya sebagian kurir gagal, API tetap membalas 200 dengan meta.partial: true dan daftar couriers_failed — bukan 502:

502 Bad Gateway

{
  "success": false,
  "error": {
    "code": "courier_upstream_error",
    "message": "Layanan kurir sedang tidak tersedia. Silakan coba lagi beberapa saat.",
    "request_id": "req_e5f7a1"
  }
}