Bantuan

Error dan batas laju

Error datang sebagai JSON dengan kode error yang stabil dan message yang ditulis untuk manusia:

{ "error": "auth_required", "message": "This tool needs a TerraLab account. Connect TerraLab in your assistant's settings; see https://terra-lab.ai/mcp." }

Cabangkan logika pada error, jangan pernah pada message: kata-katanya bisa berubah.

Error HTTP

Status	`error`	Arti	Yang perlu dilakukan
400	`invalid_input`	Body bukan objek JSON berisi argumen tool.	Perbaiki body permintaan.
400	`bad_request`	Permintaan tidak bisa dibaca.	Periksa JSON dan header.
401	`auth_required`	Tidak ada kunci atau token yang dikirim.	Kirim `Authorization: Bearer <key>`.
401	`invalid_token`	Kunci atau token tidak valid, dicabut, atau kedaluwarsa.	Buat kunci baru, atau biarkan agen masuk lagi.
401	`access_revoked`	Aplikasi diputuskan dari dashboard.	Hubungkan agen kembali.
402	`balance_required`	Panggilan gratis bulan ini habis, atau operasinya berbayar, dan saldo kosong.	Tambah saldo; jawabannya memuat `hint` dan `account_url`.
404	`not_found`	Path API itu tidak ada.	Periksa URL.
404	`unknown_tool`	Tidak ada tool dengan nama itu.	Daftar tool dengan `GET /v1/tools`.
405	`method_not_allowed`	Tool dipanggil dengan `POST`.	Pakai `POST`.
413	`too_large`	Body permintaan terlalu besar.	Kirim file yang lebih kecil atau fitur yang lebih sedikit.
429	`rate_limited`	Terlalu banyak permintaan dalam satu menit terakhir.	Tunggu sebanyak `Retry-After` detik, lalu coba lagi.
429	`daily_limit`	Akun mencapai batas pengaman hariannya.	Coba lagi besok (UTC) atau tulis ke dukungan.
503	`unavailable`	Layanan akun tidak menjawab.	Coba lagi setelah `Retry-After` detik.

Error tool

Tool yang berjalan tetapi tidak bisa menjawab mengembalikan 200 dengan isError: true. structuredContent-nya lalu memuat code, message, dan, pada umumnya, hint yang menjelaskan apa yang perlu diubah: tempat yang tidak ditemukan, area yang terlalu besar, negara yang tidak tercakup.

{
  "structuredContent": { "code": "...", "message": "...", "hint": "..." },
  "content": [{ "type": "text", "text": "..." }],
  "isError": true
}

Apa yang dihitung

Panggilan yang gagal atau tidak menemukan apa pun tidak dihitung: panggilan gratis atau jumlah yang diambil dari saldo dikembalikan. Hanya jawaban yang berisi hasil yang dihitung.

Batas laju

Setiap akun dapat melakukan 60 panggilan per menit. Melewatinya, API menjawab 429 dengan Retry-After: 60. Sebarkan pekerjaan batch sepanjang waktu, dan coba lagi dengan jeda yang bertambah:

import time
import requests

def call(url, headers, body, attempts=5):
    for attempt in range(attempts):
        response = requests.post(url, headers=headers, json=body, timeout=120)
        if response.status_code not in (429, 503):
            return response
        time.sleep(int(response.headers.get("Retry-After", 2 ** attempt)))
    return response

Coba lagi hanya untuk 429 dan 503. 401 atau 402 tidak akan lolos pada percobaan kedua.

Diperbarui 2026-10-27