Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/iFamishedX/HungerBridge/llms.txt

Use this file to discover all available pages before exploring further.

HungerBridge uses a consistent JSON envelope for every response it sends — whether the request succeeded or failed. Understanding this shape makes it straightforward to handle errors programmatically: check ok, branch on error, and surface message to logs or end users as needed.

​
Response Envelope

Every response from HungerBridge is a JSON object. Successful responses always set "ok": true and include endpoint-specific fields alongside it. Error responses always set "ok": false and include an error code string and a human-readable message.

​
Success shape

{
  "ok": true,
  // ...endpoint-specific fields
}

​
Error shape

{
  "ok": false,
  "error": "<error-code>",
  "message": "<human-readable detail>"
}

​
Error response fields

​
ok
boolean
required
Always false for error responses.
​
error
string
required
A machine-readable error code string. One of: unauthorized, method_not_allowed, bad_request, forbidden. Use this field for programmatic branching — the message field may change but error codes are stable.
​
message
string
required
A human-readable description of what went wrong. Useful for logging and debugging. See each error section below for the exact strings the server returns.

​
Error Reference

​
403 — Forbidden

Returned when the targeted endpoint has been disabled in config.yaml. The disabled check runs first in every handler — before the method check and before the auth check. Authentication is never evaluated when an endpoint is disabled. 
HTTP/1.1 403 Forbidden
Content-Type: application/json
The message field identifies which endpoint is disabled: 
{ "ok": false, "error": "forbidden", "message": "v2 ping disabled" }
{ "ok": false, "error": "forbidden", "message": "v2 info disabled" }
{ "ok": false, "error": "forbidden", "message": "v2 status disabled" }
{ "ok": false, "error": "forbidden", "message": "v2 run disabled" }
{ "ok": false, "error": "forbidden", "message": "v2 log disabled" }
{ "ok": false, "error": "forbidden", "message": "v2 tps disabled" }
{ "ok": false, "error": "forbidden", "message": "v2 players disabled" }
How to fix: Enable the endpoint in config.yaml under the relevant section (v2-endpoints, v1-endpoints, or legacy-endpoints) and restart the server.
All v2 endpoints are enabled by default. v1 and legacy endpoints are disabled by default and must be explicitly enabled in config.yaml.

​
405 — Method Not Allowed

Returned when the correct endpoint is called with the wrong HTTP method. Each endpoint accepts exactly one method — GET or POST. The message field tells you which method to use. 
HTTP/1.1 405 Method Not Allowed
Content-Type: application/json
Returned by write endpoints (/v2/run, /v2/log, /v1/run, /v1/log, /run, /log) when called with any method other than POST:
{
  "ok": false,
  "error": "method_not_allowed",
  "message": "Use POST"
}
How to fix: Match the HTTP method to what the endpoint expects. Refer to the endpoint tables on the API Overview page.

​
401 — Unauthorized

Returned when the X-Auth-Key request header is missing or does not match the key in config.yaml. This check runs after the disabled check and the method check, but before any request body is processed. 
HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "ok": false,
  "error": "unauthorized",
  "message": "Invalid X-Auth-Key"
}
How to fix: Include the correct X-Auth-Key header on every request. See Authentication for details.
GET /v1/status and GET /v1/version do not perform an auth check. Those two endpoints respond without a key as long as they are enabled.

​
400 — Bad Request

Returned when the request body is malformed, empty when content is required, or is missing a required JSON field. The message field identifies the exact problem. 
HTTP/1.1 400 Bad Request
Content-Type: application/json
Returned by /v2/run and /v1/run when the JSON body is absent or does not contain a command field:
{
  "ok": false,
  "error": "bad_request",
  "message": "Missing field: command"
}
How to fix: Send a valid JSON body (for v2/v1 endpoints) with all required fields present, or a non-empty plain-text body (for legacy endpoints).

​
Quick Reference

HTTP Statuserror fieldCause
400bad_requestMissing or empty required request field
401unauthorizedMissing or incorrect X-Auth-Key header
403forbiddenEndpoint disabled in config.yaml
405method_not_allowedWrong HTTP method (use GET or POST as indicated)

Build docs developers (and LLMs) love

Get started for freeTalk to us