Error codes V5 (beta)

The shape of an error response and the meaning of every code.

An error arrives with an HTTP status, result: "error", a code (code), a human-readable message and, when useful, details. Branch on code in your program, because message can change. The machine-readable spec is also in OpenAPI (JSON).

Error response shape

{
  "result": "error",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "code": "MISSING_PARAM",
  "message": "Required parameter is missing.",
  "elapsed_sec": 0.0011,
  "details": {
    "param_name": "when"
  }
}

{
  "result": "error",
  "version": "v5",
  "request_id": "req_5a8c1f1c-9b2d-4e7c-9abf-3f7e0a4d1b21",
  "code": "INVALID_PARAM",
  "message": "Invalid parameter value.",
  "elapsed_sec": 0.0011,
  "details": {
    "param_name": "when",
    "errors": [
      "`type` must be one of interval, daily, days, weekly, monthly."
    ]
  }
}

Code table

Code	HTTP	Meaning and what to do
`MISSING_API_KEY`	401	The `Authorization` header is missing.
`INVALID_API_KEY`	401	The API key does not match. Copy the key again.
`FORBIDDEN`	403	Access is denied (for example bots of a demo account cannot be changed).
`MISSING_PARAM`	400	A required value is missing. `details.param_name`.
`INVALID_PARAM`	400	A value is wrong. See `param_name`, `allowed`, `unknown_keys` and `errors` in `details`.
`VALIDATION_FAILED`	400	It failed the save validation. `details.errors`.
`RESOURCE_NOT_FOUND`	404	Not found.
`BOT_NOT_FOUND`	404	The bot does not exist or cannot be accessed (including bots of others and hidden bots).
`PLAN_NOT_FOUND`	404	The plan does not exist or cannot be accessed. For accounts where multiple plans are not open, every plan path returns this code.
`DATASET_NOT_FOUND`	404	The dataset does not exist or cannot be accessed.
`BULK_JOB_NOT_FOUND`	404	The bulk job id does not exist or is not yours. Jobs are kept for 30 days.
`TICKET_EXPIRED`	402	The ticket has expired or is not valid.
`CREDIT_EXHAUSTED`	402	Not enough credits. Top up and request again with a new key.
`EXECUTION_BLOCKED`	409	The collection could not start for another reason. `details.reason`.
`BOT_MAINTENANCE`	409	The bot is under maintenance. Try again shortly.
`ALREADY_RUNNING`	409	The dataset to retry is already in progress. A new collection can overlap, so it never returns this code.
`IDEMPOTENCY_KEY_REQUIRED`	400	The `Idempotency-Key` header is missing where it is required.
`IDEMPOTENCY_KEY_REUSED`	422	The same key was used for a request with different content. Use a new key per request.
`REQUEST_IN_PROGRESS`	409	The first request with this key is still being processed. Send again shortly with the same key.
`PLAN_CONDITION_BLOCKED`	422	This bot cannot have its own conditions per plan (or for a single collection).
`PLAN_UNDELETABLE`	409	Plan 1 cannot be deleted. It can only be turned off.
`PLAN_MODE_REFUSED`	422	This bot cannot be switched to plan mode. `details.reason`.
`PLAN_MODE_READONLY`	409	A reserved code. v5 does not send it today.
`PLAN_NAME_TAKEN`	422	A plan with the same name already exists.
`EXCEL_NOT_SUPPORTED_YET`	422	Collecting with Excel input is not available in v5 yet.
`EXCEL_FILE_REQUIRED`	422	Upload a file first to use Excel input.
`EXCEL_FILE_UNREADABLE`	422	The uploaded file could not be read as a spreadsheet.
`WEBHOOK_NOT_SET`	422	This bot has no webhook address, so it cannot be tested.
`RATE_LIMITED`	429	Too many requests. Try again shortly.
`INTERNAL_ERROR`	500	A server error. Contact us with the `request_id`. An error that happened before the work was handed off can be resent with the same key.

Error response shape

Code table

Related guides