Standar Respons & Error Handling

Untuk memastikan integrasi sistem berjalan dengan mulus tanpa insiden kegagalan parsial (silent failure), seluruh respons API Crevir dibungkus dalam kerangka JSON standar yang mudah diprediksi.

Standar Kode HTTP

Kami menggunakan standar kode status HTTP untuk mengkomunikasikan hasil permintaan API Anda:

Kode Status	Kategori	Keterangan
`200 OK`	Berhasil	Permintaan Anda berhasil diproses dan sistem mengembalikan payload yang relevan.
`400 Bad Request`	Klien	Parameter permintaan tidak valid, atau payload JSON tidak sesuai skema (Validation Error).
`401 Unauthorized`	Klien	API Key (Bearer Token) hilang, kadaluarsa, atau tidak valid.
`403 Forbidden`	Klien	API Key valid, namun tidak memiliki hak akses (scopes) untuk resource yang dituju.
`404 Not Found`	Klien	Resource (misal: ID Kampanye) tidak ditemukan.
`429 Too Many Requests`	Klien	Anda telah melampaui batas Rate Limit.
`500 Internal Server Error`	Server	Terjadi kegagalan di sisi infrastruktur Crevir. Kami otomatis memantau insiden ini.

Struktur Payload Error

Bila terjadi kegagalan (kode HTTP 4xx atau 5xx), sistem akan mengembalikan objek JSON yang berisi rincian penyebab error agar logger sistem internal Anda dapat mencatatnya secara terstruktur.

{
  "error": {
    "code": "validation_failed",
    "message": "Parameter 'campaign_budget' harus berupa angka positif.",
    "details": [
      {
        "field": "campaign_budget",
        "issue": "expected_number_received_string"
      }
    ],
    "request_id": "req_8x29bNcL2"
  }
}

[!TIP] Praktek Terbaik (Best Practice): Selalu simpan string request_id ke dalam log Anda. Jika Anda mengalami isu edge-case dan menghubungi Tim Enterprise Support kami, request_id ini sangat krusial untuk pelacakan trace di sisi kami.

Paginasi (Pagination)

Beberapa endpoint yang mengembalikan kumpulan data (koleksi) seperti Daftar Kampanye atau Hasil Pencarian Kreator menggunakan metode paginasi Cursor-based untuk memastikan waktu respons tetap cepat meskipun data mencapai puluhan ribu baris.

Respons API yang memuat koleksi data akan memiliki properti pagination:

{
  "data": [
    // Array of objects
  ],
  "pagination": {
    "has_more": true,
    "next_cursor": "YXJyYXljb25uZWN0aW9uOjQ="
  }
}

Untuk menarik halaman selanjutnya, sisipkan nilai next_cursor ke dalam query parameter cursor di permintaan Anda berikutnya:

curl -X GET "https://api.crevir.com/api/core/creator-profiles/search?limit=50&cursor=YXJyYXljb25uZWN0aW9uOjQ=" \
  -H "Authorization: Bearer cvt_live_xxxxx"