Reference
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.
{
"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 |
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).