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.