# Errors ## Error format An error answers with an HTTP status of `400` or higher and a JSON body in this format: ```json { "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](https://gumball.fm/developers/limits). ## 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.