DECADocs
decalabs.aiDashboard

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.

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

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).