Responses¶

Every HTTP call resolves to a response object — status, headers, parsed body, cookies, the works. HTTP errors don't throw. A 404 is just res.ok === false, not a crash.

Always check res.ok before reaching for res.data. Future-you will thank present-you.

What do you get back?¶

let res = await HTTP.get("https://api.example.com/data")

Example response¶

{
  "ok": true,
  "status": 200,
  "statusText": "OK",
  "content": "{\"status\":\"ok\"}",
  "data": { "status": "ok" },
  "isJson": true,
  "headers": {
    "content-type": "application/json; charset=utf-8",
    "content-length": "15"
  },
  "cookies": {},
  "url": "https://api.example.com/status",
  "redirected": false,
  "redirectCount": 0,
  "isStream": false,
  "responseType": "auto"
}

How to read the body¶

let res = await HTTP.get("https://api.example.com/user/1")

if (res.ok && res.isJson) {
  Bot.sendMessage("Name: " + res.data.name)
} else if (res.ok) {
  Bot.sendMessage(res.content)
}

Response types¶

Set responseType in request options:

// Auto-detect (default)
await HTTP.get(url)

// Force JSON
await HTTP.get(url, { responseType: "json" })

// Plain text
await HTTP.get(url, { responseType: "text" })

// Binary (images, files)
await HTTP.get(url, { responseType: "buffer" })

// ArrayBuffer
await HTTP.get(url, { responseType: "arrayBuffer" })

If responseType: "json" is set but the body is not valid JSON, res.ok is false and res.error.code is "INVALID_JSON". The server sent something. It just wasn't JSON.

For large or live responses, use responseType: "stream" — see Streaming.

Cookies¶

Set-Cookie headers are parsed into a flat object:

let login = await HTTP.post("https://api.example.com/login", {
  body: { username: "bot", password: process.env.API_PASSWORD }
})

let session = login.cookies.sessionId

let profile = await HTTP.get("https://api.example.com/profile", {
  headers: { Cookie: "sessionId=" + session }
})

In callback commands, cookies are also available as the cookies global alias. See http_response.

Error inspection¶

Failures return a structured object — no thrown exceptions for HTTP errors:

let res = await HTTP.get("https://api.example.com/missing")

if (!res.ok) {
  Bot.sendMessage("Error " + res.status + ": " + res.error.message)
}

Common error codes¶

In callback commands¶

When using success / error fallback commands, the same response shape is available through globals:

See Fallback Commands and http_response.

Important notes¶

• Always check res.ok before using res.data
• Default max response size is 2 MB — see Limits
• For streaming responses, see Streaming
• Validation errors (bad URL, invalid options) throw before any request is made