Errors

Error format

An error answers with an HTTP status of 400 or higher and a JSON body in this format:

{
  "error": {
    "code": "invalid_request",
    "message": "Must be a next_cursor value from this list",
    "param": "cursor",
    "doc_url": null
  }
}
Field Meaning
code A stable string. Branch on this.
message A sentence for a person. The wording can change, so don't match on it.
param The input field at fault, or null.
doc_url A link to more detail, or null.

Error codes

Code Status What it means What to do
invalid_request 400 A parameter is missing, malformed, or not one the operation has. param names it. Fix the parameter and send the request again.
unauthenticated 401 No valid API key or access token came with the request. Send a key as Authorization: Bearer gum_..., or connect the app again.
key_revoked 401 The key was revoked. Create a new key.
key_expired 401 The key passed its expiry date. Create a new key.
account_disabled 403 The account can't sign in to Gumball. Contact Gumball.
account_not_approved 403 Gumball hasn't approved the account yet. Wait for approval.
terms_not_accepted 403 The account hasn't accepted the current terms of service. Sign in to gumball.fm and accept them.
forbidden 403 The account type can't use this operation, or a read-only key or connection called one that changes data. Call GET /v1/me to see the account's role and access level.
not_found 404 No record has this ID, or the account can't reach it. Check the ID.
conflict 409 The record isn't in a state the operation allows. For example, the cart is already reserved, or an Idempotency-Key was reused with different input. Read the message, read the record again, and decide whether to retry.
slots_unavailable 409 One or more ad slots can't be added or reserved. The message names each one. Remove those slots, then try again.
limit_reached 429 The account reached an operation's cap, such as 10 reserves in 24 hours. Wait, then try again.
rate_limited 429 The IP address sent too many requests. Wait a minute, then send the request again.
internal_error 500 Something failed at Gumball. Retry later. If it persists, send Gumball the request ID.

New codes can appear. Treat a code you don't recognize by its HTTP status.

A rate_limited answer comes from the network edge, before the request reaches the API, so it carries no Request-Id header. See Rate limits and safe retries.

Request IDs

Every response from the API, success or error, carries a Request-Id header. A rate_limited answer is the one that doesn't; a limit_reached answer, also a 429, does. Log it. When you ask Gumball about a request, include its ID.

Errors in the MCP server

A tool call that fails returns the same JSON, as text, in a tool result marked as an error. An agent can read code and correct its next call.

Read this page as plain text.