Errors

Every error returns the same envelope — a readable message for people, and a stable errorCode for your code to branch on:

404 Not Found

{
  "success": false,
  "message": "Run not found.",
  "errorCode": "RUN_NOT_FOUND"
}

Branch on errorCode (and the status), not on message — messages are written for people and can change.

Status codes

Status	When
`400 Bad Request`	The request is invalid, or the action can't be done right now. `message` says why.
`401 Unauthorized`	The API key is missing, malformed, or revoked.
`402 Payment Required`	The data exists, but the run's final payment hasn't settled.
`403 Forbidden`	The key is valid but lacks the permission — or, for pipelines, you aren't allowed that pipeline.
`404 Not Found`	The resource doesn't exist, or you don't have access to it.
`410 Gone`	The file existed but was removed by your retention period. Retrying won't help.
`429 Too Many Requests`	Rate limited. Wait `Retry-After` seconds.
`500 Internal Server Error`	Something went wrong on our side. Retry with backoff, and include the response's `correlationId` if you contact us.

Error codes

Code	Status	Meaning
`RUN_START_FAILED`	400	`run` couldn't start the agent; `message` says why. `start-job` returns `400` with a `message` and no code.
`INVALID_STATE`	400	The `state` filter isn't `all`, `active`, `succeeded`, or `failed`.
`INVALID_ATTENTION_FILTER`	400	`attention` isn't `tracked` or `ignored`, or was used without `state=failed`.
`NO_FILE_EXPORT`	400	The run produced no file.
`INVALID_ACCESS_POLICY`	400	The dataset can't be shared that way — for example, your account has no company.
`INVALID_SAVED_QUERY`	400	The saved query is invalid; `message` says why.
`PAYMENT_REQUIRED`	402	The run's final payment hasn't settled.
`FORBIDDEN`	403	You aren't allowed this pipeline.
`AGENT_NOT_FOUND`	404	No such agent, or it isn't assigned to you.
`RUN_NOT_FOUND`	404	No such run, or no access to it.
`JOB_NOT_FOUND`	404	No such job, or no access to it.
`GROUP_NOT_FOUND`	404	No such group — or, for an edit, not one you can manage.
`GROUP_RUN_NOT_FOUND`	404	No such group run, or no access to it.
`PIPELINE_NOT_FOUND`	404	No such pipeline — or, for an edit, not one you can manage.
`PIPELINE_RUN_NOT_FOUND`	404	No such pipeline run, or no access to it.
`NOT_FOUND`	404	No such schedule, group member, or run to retry.
`DATASET_NOT_FOUND`	404	No such dataset, or no access to it.
`DATASET_FILE_NOT_FOUND`	404	The dataset's file isn't available.
`DATASETS_NOT_FOUND`	404	None of the datasets in a bulk export have a file available.
`EXPORT_NOT_FOUND`	404	No such stored dataset, or not one you can delete.
`SAMPLE_OUTPUT_NOT_FOUND`	404	The agent has no sample output.
`API_KEY_NOT_FOUND`	404	No such key among yours.
`EXPORT_EXPIRED`	410	Removed by retention.
`BULK_EXPORT_CAPACITY_EXCEEDED`	429	A bulk export is already running for your account or company. Retry after `Retry-After`.

Retrying

Retry 429 (after Retry-After) and 5xx (with exponential backoff).
Don't retry 400, 401, 403, 404, or 410 unchanged — the same request will fail the same way.

Status codes

Error codes

Retrying

On this page