Errors - Radarkit

The shape

When a call fails, the body has an error and no data:

{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "One or more parameters are invalid.",
    "details": [
      { "path": "from", "message": "The from field must match the format Y-m-d." }
    ]
  },
  "request_id": "req_01j9x4s6b7c8d9e0f1g2h3i4j5"
}

code is stable. Build on it, not on the message.
message is for people. It may change.
details appears when there is more to say: which field failed, how long to wait, which id already exists.
request_id is also in the X-Request-Id header. Quote it when you contact support.

Each endpoint page lists the codes it can return. Over MCP the same body comes back as the tool’s error text.

Every code

Key and plan

Code	Status	Meaning	What to do
`UNAUTHENTICATED`	401	No key, a wrong key, or a revoked or expired key.	Check the header. Create a new key if yours was revoked.
`KEY_IN_QUERY`	400	The key was in the URL.	Move it to the `Authorization` header.
`AUTH_RATE_LIMITED`	429	Too many failed logins from your address.	Wait `Retry-After` seconds.
`API_FROZEN`	403	API access for the account is paused.	Contact support.
`PLAN_INACTIVE`	402	The key owner’s plan is not active.	Renew the plan.
`PLAN_NO_API`	403	The plan does not include API access.	Upgrade.
`OWNER_PLAN_INACTIVE`	402	The project owner’s plan is not active.	The owner renews.
`API_DISABLED`	503	The API is switched off for maintenance.	Try again later.

Access

Code	Status	Meaning	What to do
`SCOPE_MISSING`	403	The key lacks the permission this call needs.	Create a key with it.
`PERMISSION_DENIED`	403	Your seat on the project cannot do this.	Ask the owner or an admin.
`PROJECT_FORBIDDEN`	403	The key cannot reach that project.	Use a key that can.

Not found

Code	Status	Meaning	What to do
`PROJECT_NOT_FOUND`	404	No project with that id.	Check the id with List projects.
`NOT_FOUND`	404	No response or export with that id in this project.	Check the id.
`TOPIC_NOT_FOUND`	404	No active topic with that id.	List topics.
`PROMPT_NOT_FOUND`	404	No active prompt with that id.	List prompts.
`RUN_NOT_FOUND`	404	No content run with that id.	Check the id.

Input

Code	Status	Meaning	What to do
`VALIDATION_FAILED`	422	A parameter is missing or wrong. `details` says which.	Fix it.
`DATE_RANGE_TOO_LARGE`	400	The window is longer than the endpoint allows.	Shorten it or export.
`INVALID_CURSOR`	400	The cursor does not match this request.	Start again from the first page.
`NO_MODELS`	422	The owner’s plan has no AI models.	Contact support.
`EXPORT_EMPTY`	422	The selection has no rows.	Widen it.
`EXPORT_TOO_LARGE`	422	More rows than one file may hold.	Split by date or topic.
`CONTENT_REJECTED`	422	The Content agent refused the request.	Read the message.

Balances

Code	Status	Meaning	What to do
`INSUFFICIENT_CREDITS`	402	No API credits left.	Wait for renewal or top up.
`INSUFFICIENT_EXPORT_ROWS`	402	Not enough Export rows for this export.	Narrow it or top up.
`INSUFFICIENT_REALTIME_CREDITS`	402	The owner has no realtime credits.	The owner tops up.
`INSUFFICIENT_CONTENT_CREDITS`	402	The owner has no AI content credits.	The owner tops up.
`PROMPT_LIMIT_REACHED`	402	The plan’s prompt limit is used up.	Upgrade or remove prompts.

Limits

Code	Status	Meaning	What to do
`RATE_LIMITED`	429	Too many calls.	Wait `Retry-After` seconds and retry.
`PROMPTS_DAILY_CAP`	429	This key added its daily maximum of prompts.	Retry after `Retry-After`.

Conflicts

Code	Status	Meaning	What to do
`TOPIC_EXISTS`	409	A topic with that name exists. `details.topic_id` has it.	Use that id.
`PROMPT_PROCESSING`	409	The prompt is being run right now.	Wait for the run to finish.
`EXPORT_IN_PROGRESS`	409	You already have an export running.	Wait for it to finish.
`EXPORT_NOT_READY`	409	The file is not ready yet.	Poll Get export.
`RUN_NOT_RETRYABLE`	409	The run is not failed or cancelled.	Nothing to do.

Server

Code	Status	Meaning	What to do
`QUERY_TIMEOUT`	504	The query took too long. Nothing was charged.	Narrow the range or export.
`INTERNAL`	500	Something broke on our side. Nothing was charged.	Retry once, then contact support with the `request_id`.

Retry only these

RATE_LIMITED, AUTH_RATE_LIMITED, PROMPTS_DAILY_CAP and QUERY_TIMEOUT after the wait they ask for. INTERNAL once. Everything else will fail the same way again until you change something.