# Errors

> Every error has a code, a message and the next step, so an agent can recover on its own.

When a call cannot be answered, DECA returns an error object instead of a result. Over REST it comes with a non-`200` status. Over MCP the tool result has `isError: true` and the same object in `structuredContent`.

```json
{
  "error": {
    "code": "market_not_supported",
    "message": "We only price markets where we have measured what a click costs: US, GB, CA. Not: DE.",
    "next": "use markets from US, GB, CA"
  }
}
```

| Field | Description |
|---|---|
| `code` | A stable identifier. Branch on this, never on the message. |
| `message` | What went wrong, in a sentence a person or a model can read. |
| `next` | What to do about it. Present when there is something to do. |
| `details` | More about the error, such as the reasons a quote declined each option. Optional. |

## Codes

| Code | Status | What it means | What to do |
|---|---|---|---|
| `idea_missing` | 400 | `quote_test` got neither `idea_id` nor `idea.pitch` | Send one of them |
| `idea_too_short` | 400 | `idea.pitch` is under 20 characters | Say who it is for and what it does for them |
| `idea_too_long` | 400 | `idea.pitch` is over 2,000 characters | Shorten it |
| `idea_not_found` | 404 | No public idea has that id | Call `get_ideas` again; ideas leave after two weeks or when a founder takes them |
| `market_not_supported` | 400 | A market DECA has not priced | Use `US`, `GB` or `CA` |
| `no_reliable_option` | 400 | No budget up to $2,000 can read this idea reliably | Try other markets, or sharpen the idea; reasons in `details` |
| `radar_unavailable` | 503 | The radar has nothing to show | Try again in a few minutes |
| `key_required` | 401 | The tool needs an API key, such as `get_my_ideas` | Make a key in MCP & API |
| `invalid_key` | 401 | The API key is not one DECA made | Check it, or call without a key |
| `key_revoked` | 401 | The API key was revoked | Make a new one in MCP & API |
| `scope_missing` | 403 | The key may not use this tool | Add the scope to the key |
| `quote_invalid` · `quote_expired` | 400 | The quote is not DECA's, or older than 30 minutes | Call `quote_test` again |
| `option_not_in_quote` | 400 | The quote has no such option | Use one of its options |
| `payments_not_open` | 503 | Real payments are switched off for the moment | Use the sandbox |
| `idea_invalid` | 400 | `POST /api/agent/score` got no `idea.pitch` of 20 to 2,000 characters; nothing was charged | Send `{ idea: { pitch } }` |
| `not_an_idea` | 422 | The text sent to be scored is not a product idea; nothing was charged | Say who it is for and what it does |
| `engine_unavailable` · `score_failed` | 503 | The idea could not be scored this time; nothing was charged | Try again in a few minutes |
| `payments_unavailable` | 503 | The payment service could not be reached; nothing was charged | Retry later, or use `sandbox: true` |
| `payment_invalid` | 402 | The payment does not match the request, or was refused | Pay the exact request again |
| `payment_failed` | 402 | The payment could not be settled; nothing was charged | Check the wallet's balance |
| `payment_already_used` | 409 | That payment already opened a test or bought a score | Read the test, or pay again |
| `idempotency_key_used` | 409 | The idempotency key belongs to another payment | Use a new key for a new test |
| `over_cap` · `over_month_cap` | 403 | Above the key's cap per test or per month | A smaller option, or a higher cap |
| `webhook_invalid` | 400 | `webhook_url` is not a public https address | Fix it or leave it out |
| `test_not_found` | 404 | No test you can read has that id | Send the key or the access token |
| `cannot_cancel` | 409 | The test is past review | Write to hello@decalabs.ai |
| `rate_limited` | 429 | Too many requests from this address | Wait for `Retry-After` seconds |
| `bad_json` | 400 | The body is not a JSON object | Send `content-type: application/json` with an object |
| `wrong_method` | 405 | `GET` where `POST` is needed, or the reverse | Use the method in `Allow` |
| `unknown_tool` | 404 | No tool or endpoint by that name | Use one listed in [the overview](https://app.decalabs.ai/docs) |

New codes may be added. Treat a code you do not know as a failure with its `message`.

## Protocol errors

Over MCP, a request that is not valid JSON-RPC gets a JSON-RPC error instead: `-32700` parse error, `-32600` invalid request, `-32601` method not found, `-32602` unknown tool, `-32603` internal error, `-32000` too many requests, `-32001` API key refused (code in `data.code`).

Source: https://app.decalabs.ai/docs/reference/errors
